 PaneContainerView = require './pane-container-view'
 Editor = require './editor'
 
-# Public: The container for the entire Atom application.
-#
-# An instance of this class is always available as the `atom.workspaceView`
-# global.
-#
-# ## Commands
-#
-#  * `application:about` - Opens the about dialog.
-#  * `application:show-settings` - Opens the preference pane in the currently
-#    focused editor.
-#  * `application:quit` - Quits the entire application.
-#  * `application:hide` - Hides the entire application.
-#  * `application:hide-other-applications` - Hides other applications
-#    running on the system.
-#  * `application:unhide-other-applications` - Shows other applications
-#    that were previously hidden.
-#  * `application:new-window` - Opens a new {AtomWindow} with no {Project}
-#    path.
-#  * `application:new-file` - Creates a new file within the focused window.
-#    Note: only one new file may exist within an {AtomWindow} at a time.
-#  * `application:open` - Prompts the user for a path to open in a new {AtomWindow}
-#  * `application:minimize` - Minimizes the currently focused {AtomWindow}
-#  * `application:zoom` - Expands the window to fill the screen or returns it to
-#    it's original unzoomed size.
-#  * `application:bring-all-windows-to-front` - Brings all {AtomWindow}s to the
-#    the front.
+# Public: The top-level view for the entire window. An instance of this class is
+# available via the `atom.workspaceView` global.
+#
+# It is backed by a model object, an instance of {Workspace}, which is available
+# via the `atom.workspace` global or {::getModel}. You should prefer to interact
+# with the model object when possible, but it won't always be possible with the
+# current API.
+#
+# ## Adding Perimiter Panels
+#
+# Use the following methods if possible to attach panels to the perimiter of the
+# workspace rather than manipulating the DOM directly to better insulate you to
+# changes in the workspace markup:
+#
+# * {::prependToTop}
+# * {::appendToTop}
+# * {::prependToBottom}
+# * {::appendToBottom}
+# * {::prependToLeft}
+# * {::appendToLeft}
+# * {::prependToRight}
+# * {::appendToRigt}
 #
 # ## Requiring in package specs
+#
+# If you need a `WorkspaceView` instance to test your package, require it via
+# the built-in `atom` module.
 #
 # ```coffee
 #   {WorkspaceView} = require 'atom'
 # ```
+#
+# You can assign it to the `atom.workspaceView` global in the spec or just use
+# it as a local, depending on what you're trying to accomplish. Building the
+# `WorkspaceView` is currently expensive, so you should try build a {Workspace}
+# instead if possible.
 module.exports =
 class WorkspaceView extends View
   Delegator.includeInto(this)

  # Deprecated
  getActivePane: ->
    @getActivePaneView()

    else
      @setTitle('untitled')

  # Sets the application's title.
  setTitle: (title) ->
    document.title = title

  # 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: Prepend an element or view to the panels at the top of the
  # workspace.
  prependToTop: (element) ->
    @vertical.prepend(element)

  # Public: Append an element or view to the panels at the top of the workspace.
  appendToTop: (element) ->
    @panes.before(element)

  # Public: Prepend an element or view to the panels at the bottom of the
  # workspace.
  prependToBottom: (element) ->
    @panes.after(element)

  # Public: Append an element or view to the panels at the bottom of the
  # workspace.
  appendToBottom: (element) ->
    @vertical.append(element)

  # Public: Prepend an element or view to the panels at the left of the
  # workspace.
  prependToLeft: (element) ->
    @horizontal.prepend(element)

  # Public: Append an element or view to the panels at the left of the
  # workspace.
  appendToLeft: (element) ->
    @vertical.before(element)

  # Public: Prepend an element or view to the panels at the right of the
  # workspace.
  prependToRight: (element) ->
    @vertical.after(element)

  # Public: Append an element or view to the panels at the right of the
  # workspace.
  appendToRight: (element) ->
    @horizontal.append(element)

  # 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: Get the view associated with the active pane item.
  #
  # Returns a view.
  getActiveView: ->
    @panes.getActiveView()

  # Focus the previous pane by id.
  focusPreviousPaneView: -> @model.activatePreviousPane()

  # Focus the next pane by id.
  focusNextPaneView: -> @model.activateNextPane()

  # Public: Focus the pane directly above the active pane.
  focusPaneViewAbove: -> @panes.focusPaneViewAbove()

  # Public: Focus the pane directly below the active pane.
  focusPaneViewBelow: -> @panes.focusPaneViewBelow()

  # Public: Focus the pane directly to the left of the active pane.
  focusPaneViewOnLeft: -> @panes.focusPaneViewOnLeft()

  # Public: Focus the pane directly to the right of the active pane.
  focusPaneViewOnRight: -> @panes.focusPaneViewOnRight()

  # 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: 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)
