diff --git a/src/dock.js b/src/dock.js
index 0aeab7336..a67ad3ab9 100644
--- a/src/dock.js
+++ b/src/dock.js
@@ -15,7 +15,9 @@ const TOGGLE_BUTTON_VISIBLE_CLASS = 'atom-dock-toggle-button-visible'
 const CURSOR_OVERLAY_VISIBLE_CLASS = 'atom-dock-cursor-overlay-visible'
 
 // Extended: A container at the edges of the editor window capable of holding items.
-// You should not create a `Dock` directly, instead use {Workspace::open}.
+// You should not create a Dock directly. Instead, access one of the three docks of the workspace
+// via {::getLeftDock}, {::getRightDock}, and {::getBottomDock} or add an item to a dock via
+// {Workspace::open}.
 module.exports = class Dock {
   constructor (params) {
     this.handleResizeHandleDragStart = this.handleResizeHandleDragStart.bind(this)