diff --git a/src/workspace.js b/src/workspace.js
index a3938fcd9..f567e83b4 100644
--- a/src/workspace.js
+++ b/src/workspace.js
@@ -34,28 +34,28 @@ const WorkspaceCenter = require('./workspace-center')
 //
 // ### Required Methods
 //
-// #### `getTitle` Returns the title of the item to display on its associated
+// #### `getTitle()` Returns the title of the item to display on its associated
 // #### tab.
 //
 // ### Optional Methods
 //
-// #### `getElement`
+// #### `getElement()`
 //
 // If your item already *is* a DOM element, you do not need to implement this
 // method. Otherwise it should return the element you want to display to
 // represent this item.
 //
-// #### `destroy`
+// #### `destroy()`
 //
 // Destroys the item. This will be called when the item is removed from its
 // parent pane.
 //
-// #### `onDidDestroy`
+// #### `onDidDestroy(callback)`
 //
 // Called by the workspace so it can be notified when the item is destroyed.
 // Must return a {Disposable}.
 //
-// #### `serialize`
+// #### `serialize()`
 //
 // Serialize the state of the item. Must return an object that can be passed to
 // `JSON.stringify`. The state should include a field called `deserializer`,
@@ -63,11 +63,11 @@ const WorkspaceCenter = require('./workspace-center')
 // invoked on items when serializing the workspace so they can be restored to
 // the same location later.
 //
-// #### `getURI`
+// #### `getURI()`
 //
 // Returns the URI associated with the item.
 //
-// #### `getPreferredLocation`
+// #### `getDefaultLocation()`
 //
 // Tells the workspace where your item should be opened in absence of a user
 // override. Items can appear in the center or in a dock on the left, right, or
@@ -77,18 +77,22 @@ const WorkspaceCenter = require('./workspace-center')
 // `'right'`, `'bottom'`. If this method is not defined, `'center'` is the
 // default.
 //
-// #### `getAllowedLocations`
+// #### `getAllowedLocations()`
 //
 // Tells the workspace where this item can be moved. Returns an {Array} of one
 // or more of the following values: `'center'`, `'left'`, `'right'`, or
 // `'bottom'`.
 //
-// #### `isPermanentDockItem`
+// #### `isPermanentDockItem()`
 //
-// Tells the workspace whether or not this item can be closed by the user. Use
-// of this feature is discouraged unless there's a very good reason not to allow
-// users to close your item. Items can be made permanent *only* when they are
-// contained in docks. Center pane items can always be removed.
+// Tells the workspace whether or not this item can be closed by the user by
+// clicking an `x` on its tab. Use of this feature is discouraged unless there's
+// a very good reason not to allow users to close your item. Items can be made
+// permanent *only* when they are contained in docks. Center pane items can
+// always be removed. Note that it is currently still possible to close dock
+// items via the `Close Pane` option in the context menu and via Atom APIs, so
+// you should still be prepared to handle your dock items being destroyed by the
+// user even if you implement this method.
 //
 // #### `save()`
 //
@@ -98,33 +102,33 @@ const WorkspaceCenter = require('./workspace-center')
 //
 // Saves the item to the specified path.
 //
-// #### `getPath`
+// #### `getPath()`
 //
 // Returns the local path associated with this item. This is only used to set
 // the initial location of the "save as" dialog.
 //
-// #### `isModified`
+// #### `isModified()`
 //
 // Returns whether or not the item is modified to reflect modification in the
 // UI.
 //
-// #### `onDidChangeModified`
+// #### `onDidChangeModified()`
 //
 // Called by the workspace so it can be notified when item's modified status
 // changes. Must return a {Disposable}.
 //
-// #### `copy`
+// #### `copy()`
 //
 // Create a copy of the item. If defined, the workspace will call this method to
 // duplicate the item when splitting panes via certain split commands.
 //
-// #### `onDidTerminatePendingState`
+// #### `onDidTerminatePendingState(callback)`
 //
 // If the workspace is configured to use *pending pane items*, the workspace
 // will subscribe to this method to terminate the pending state of the item.
 // Must return a {Disposable}.
 //
-// #### `shouldPromptToSave`
+// #### `shouldPromptToSave()`
 //
 // This method indicates whether Atom should prompt the user to save this item
 // when the user closes or reloads the window. Returns a boolean.