diff --git a/src/path-watcher.js b/src/path-watcher.js
index 88f9cd77d..69bf36da0 100644
--- a/src/path-watcher.js
+++ b/src/path-watcher.js
@@ -339,7 +339,7 @@ class NativeWatcher {
 // ```js
 // const {watchPath} = require('atom')
 //
-// const disposable = watchPath('/var/log', {}, events => {
+// const disposable = await watchPath('/var/log', {}, events => {
 //   console.log(`Received batch of ${events.length} events.`)
 //   for (const event of events) {
 //     // "created", "modified", "deleted", "renamed"
@@ -424,6 +424,8 @@ class PathWatcher {
   // intend to assert about because there will be a delay between the instantiation of the watcher and the activation
   // of the underlying OS resources that feed it events.
   //
+  // PathWatchers acquired through `watchPath` are already started.
+  //
   // ```js
   // const {watchPath} = require('atom')
   // const ROOT = path.join(__dirname, 'fixtures')
@@ -617,7 +619,7 @@ class PathWatcherManager {
 // ```js
 // const {watchPath} = require('atom')
 //
-// const disposable = watchPath('/var/log', {}, events => {
+// const disposable = await watchPath('/var/log', {}, events => {
 //   console.log(`Received batch of ${events.length} events.`)
 //   for (const event of events) {
 //     // "created", "modified", "deleted", "renamed"
diff --git a/src/project.coffee b/src/project.coffee
index 2f1b56566..756fd756a 100644
--- a/src/project.coffee
+++ b/src/project.coffee
@@ -140,6 +140,10 @@ class Project extends Model
   #
   # To watch paths outside of open projects, use the `watchPaths` function instead; see {PathWatcher}.
   #
+  # When writing tests against functionality that uses this method, be sure to wait for the
+  # {Promise} returned by {getWatcherPromise()} before manipulating the filesystem to ensure that
+  # the watcher is receiving events.
+  #
   # * `callback` {Function} to be called with batches of filesystem events reported by
   #   the operating system.
   #    * `events` An {Array} of objects that describe a batch of filesystem events.