     else
       @setTitle('untitled')
 
-  # Public: Sets the application's title.
+  # Sets the application's title.
   setTitle: (title) ->
     document.title = title
 
-  # Returns an Array of  all of the application's {EditorView}s.
+  # Get all editor views.
+  #
+  # You should prefer {Workspace::getEditors} unless you absolutely need access
+  # to the view objects. Also consider using {::eachEditorView}, which will call
+  # a callback for all current and *future* editor views.
+  #
+  # Returns an {Array} of {EditorView}s.
   getEditorViews: ->
     @panes.find('.pane > .item-views > .editor').map(-> $(this).view()).toArray()
 
-  # Public: Prepends the element to the top of the window.
+  # Public: Prepend an element or view to the panels at the top of the
+  # workspace.
   prependToTop: (element) ->
     @vertical.prepend(element)
 
-  # Public: Appends the element to the top of the window.
+  # Public: Append an element or view to the panels at the top of the workspace.
   appendToTop: (element) ->
     @panes.before(element)
 
-  # Public: Prepends the element to the bottom of the window.
+  # Public: Prepend an element or view to the panels at the bottom of the
+  # workspace.
   prependToBottom: (element) ->
     @panes.after(element)
 
-  # Public: Appends the element to bottom of the window.
+  # Public: Append an element or view to the panels at the bottom of the
+  # workspace.
   appendToBottom: (element) ->
     @vertical.append(element)
 
-  # Public: Prepends the element to the left side of the window.
+  # Public: Prepend an element or view to the panels at the left of the
+  # workspace.
   prependToLeft: (element) ->
     @horizontal.prepend(element)
 
-  # Public: Appends the element to the left side of the window.
+  # Public: Append an element or view to the panels at the left of the
+  # workspace.
   appendToLeft: (element) ->
     @vertical.before(element)
 
-  # Public: Prepends the element to the right side of the window.
+  # Public: Prepend an element or view to the panels at the right of the
+  # workspace.
   prependToRight: (element) ->
     @vertical.after(element)
 
-  # Public: Appends the element to the right side of the window.
+  # Public: Append an element or view to the panels at the right of the
+  # workspace.
   appendToRight: (element) ->
     @horizontal.append(element)
 
-  # Public: Returns the currently focused {PaneView}.
+  # Public: Get the active pane view.
+  #
+  # Prefer {Workspace::getActivePane} if you don't actually need access to the
+  # view.
+  #
+  # Returns a {PaneView}.
   getActivePaneView: ->
     @panes.getActivePane()
 
-  # Public: Returns the currently focused item from within the focused {PaneView}
-  getActivePaneItem: ->
-    @model.activePaneItem
-
-  # Public: Returns the view of the currently focused item.
+  # Public: Get the view associated with the active pane item.
+  #
+  # Returns a view.
   getActiveView: ->
     @panes.getActiveView()
 
-  # Public: Focuses the previous pane by id.
+  # Focus the previous pane by id.
   focusPreviousPaneView: -> @model.activatePreviousPane()
 
-  # Public: Focuses the next pane by id.
+  # Focus the next pane by id.
   focusNextPaneView: -> @model.activateNextPane()
 
-  # Public: Focuses the pane directly above the active pane.
+  # Public: Focus the pane directly above the active pane.
   focusPaneViewAbove: -> @panes.focusPaneViewAbove()
 
-  # Public: Focuses the pane directly below the active pane.
+  # Public: Focus the pane directly below the active pane.
   focusPaneViewBelow: -> @panes.focusPaneViewBelow()
 
-  # Public: Focuses the pane directly to the left of the active pane.
+  # Public: Focus the pane directly to the left of the active pane.
   focusPaneViewOnLeft: -> @panes.focusPaneViewOnLeft()
 
-  # Public: Focuses the pane directly to the right of the active pane.
+  # Public: Focus the pane directly to the right of the active pane.
   focusPaneViewOnRight: -> @panes.focusPaneViewOnRight()
 
-  # Public: Fires a callback on each open {PaneView}.
+  # Public: Register a function to be called for every current and future
+  # pane view in the workspace.
+  #
+  # callback - A {Function} with a {PaneView} as its only argument.
+  #
+  # Returns a subscription object with an `.off` method that you can call to
+  # unregister the callback.
   eachPaneView: (callback) ->
     @panes.eachPaneView(callback)
 
+  # Public: Get all existing pane views.
+  #
+  # Prefer {Workspace::getPanes} if you don't need access to the view objects.
+  # Also consider using {::eachPaneView} or {Workspace::eachPane} if you want
+  # to register a callback for all current and *future* pane views or panes.
+  #
   # Returns an Array of all open {PaneView}s.
   getPaneViews: ->
     @panes.getPanes()
 
-  # Public: Fires a callback on each open {EditorView}.
+  # Public: Register a function to be called for every current and future
+  # editor view in the workspace.
+  #
+  # callback - A {Function} with an {EditorView} as its only argument.
+  #
+  # Returns a subscription object with an `.off` method that you can call to
+  # unregister the callback.
   eachEditorView: (callback) ->
     callback(editor) for editor in @getEditorViews()
     attachedCallback = (e, editor) -> callback(editor)

  # Deprecated
  getActivePane: ->
    @getActivePaneView()

  afterAttach: (onDom) ->
    @focus() if onDom

  # Prompts to save all unsaved items
  confirmClose: ->
    @panes.confirmClose()

  # Updates the application's title, based on whichever file is open.
  updateTitle: ->
    if projectPath = atom.project.getPath()
      if item = @getActivePaneItem()
