diff --git a/src/default-directory-provider.coffee b/src/default-directory-provider.coffee
index da2d17593..6b05a582f 100644
--- a/src/default-directory-provider.coffee
+++ b/src/default-directory-provider.coffee
@@ -37,7 +37,7 @@ class DefaultDirectoryProvider
   # * `uri` {String} The path to the directory to add. This is guaranteed not to
   # be contained by a {Directory} in `atom.project`.
   #
-  # Returns a Promise that resolves to:
+  # Returns a {Promise} that resolves to:
   # * {Directory} if the given URI is compatible with this provider.
   # * `null` if the given URI is not compatibile with this provider.
   directoryForURI: (uri) ->
diff --git a/src/project.coffee b/src/project.coffee
index 714511f9a..008d81e3e 100644
--- a/src/project.coffee
+++ b/src/project.coffee
@@ -329,7 +329,7 @@ class Project extends Model
   #
   # * `filePath` A {String} representing a path. If `null`, an "Untitled" buffer is created.
   #
-  # Returns a promise that resolves to the {TextBuffer}.
+  # Returns a {Promise} that resolves to the {TextBuffer}.
   bufferForPath: (absoluteFilePath) ->
     existingBuffer = @findBufferForPath(absoluteFilePath) if absoluteFilePath?
     if existingBuffer
@@ -349,7 +349,7 @@ class Project extends Model
   # * `absoluteFilePath` A {String} representing a path.
   # * `text` The {String} text to use as a buffer.
   #
-  # Returns a promise that resolves to the {TextBuffer}.
+  # Returns a {Promise} that resolves to the {TextBuffer}.
   buildBuffer: (absoluteFilePath) ->
     buffer = new TextBuffer({filePath: absoluteFilePath})
     @addBuffer(buffer)
diff --git a/src/workspace.coffee b/src/workspace.coffee
index 4682c2321..c04058119 100644
--- a/src/workspace.coffee
+++ b/src/workspace.coffee
@@ -403,7 +403,7 @@ class Workspace extends Model
   #     If `false`, only the active pane will be searched for
   #     an existing item for the same URI. Defaults to `false`.
   #
-  # Returns a promise that resolves to the {TextEditor} for the file URI.
+  # Returns a {Promise} that resolves to the {TextEditor} for the file URI.
   open: (uri, options={}) ->
     searchAllPanes = options.searchAllPanes
     split = options.split
@@ -546,7 +546,7 @@ class Workspace extends Model
   # Public: Asynchronously reopens the last-closed item's URI if it hasn't already been
   # reopened.
   #
-  # Returns a promise that is resolved when the item is opened
+  # Returns a {Promise} that is resolved when the item is opened
   reopenItem: ->
     if uri = @destroyedItemURIs.pop()
       @open(uri)
@@ -883,7 +883,7 @@ class Workspace extends Model
   #     with number of paths searched.
   # * `iterator` {Function} callback on each file found.
   #
-  # Returns a `Promise` with a `cancel()` method that will cancel all
+  # Returns a {Promise} with a `cancel()` method that will cancel all
   # of the underlying searches that were started as part of this scan.
   scan: (regex, options={}, iterator) ->
     if _.isFunction(options)
@@ -986,7 +986,7 @@ class Workspace extends Model
   # * `iterator` A {Function} callback on each file with replacements:
   #   * `options` {Object} with keys `filePath` and `replacements`.
   #
-  # Returns a `Promise`.
+  # Returns a {Promise}.
   replace: (regex, replacementText, filePaths, iterator) ->
     new Promise (resolve, reject) =>
       openPaths = (buffer.getPath() for buffer in @project.getBuffers())