Merge pull request #3583 from atom/bo-final-docs-pass

Final docs pass

package.json

@@ -57,7 +57,7 @@
     "serializable": "^1",
     "space-pen": "3.4.7",
     "temp": "0.7.0",
-    "text-buffer": "^3.2.5",
+    "text-buffer": "^3.2.6",
     "theorist": "^1.0.2",
     "underscore-plus": "^1.5.1",
     "vm-compatibility-layer": "0.1.0"

src/atom.coffee

@@ -226,40 +226,34 @@ class Atom extends Model
     @emitter.on 'did-beep', callback
 
   ###
-  Section: Atom Metadata
+  Section: Atom Details
   ###
 
-  # Essential: Is the current window in development mode?
+  # Public: Is the current window in development mode?
   inDevMode: ->
     @getLoadSettings().devMode
 
-  # Essential: Is the current window running specs?
+  # Public: Is the current window running specs?
   inSpecMode: ->
     @getLoadSettings().isSpec
 
-  # Essential: Get the version of the Atom application.
+  # Public: Get the version of the Atom application.
   #
   # Returns the version text {String}.
   getVersion: ->
     @appVersion ?= @getLoadSettings().appVersion
 
-  # Essential: Determine whether the current version is an official release.
+  # Public: Determine whether the current version is an official release.
   isReleasedVersion: ->
     not /\w{7}/.test(@getVersion()) # Check if the release is a 7-character SHA prefix
 
-  # Essential: Get the directory path to Atom's configuration area.
+  # Public: Get the directory path to Atom's configuration area.
   #
   # Returns the absolute path to `~/.atom`.
   getConfigDirPath: ->
     @constructor.getConfigDirPath()
 
-  # Extended: Get the load settings for the current window.
-  #
-  # Returns an {Object} containing all the load setting key/value pairs.
-  getLoadSettings: ->
-    @constructor.getLoadSettings()
-
-  # Extended: Get the time taken to completely load the current window.
+  # Public: Get the time taken to completely load the current window.
   #
   # This time include things like loading and activating packages, creating
   # DOM elements for the editor, and reading the config.
@@ -269,6 +263,12 @@ class Atom extends Model
   getWindowLoadTime: ->
     @loadTime
 
+  # Public: Get the load settings for the current window.
+  #
+  # Returns an {Object} containing all the load setting key/value pairs.
+  getLoadSettings: ->
+    @constructor.getLoadSettings()
+
   ###
   Section: Managing The Atom Window
   ###

src/cursor.coffee

@@ -166,7 +166,7 @@ class Cursor extends Model
     @getBufferPosition().isEqual(@getCurrentLineBufferRange().end)
 
   ###
-  Section: Info about the cursor position
+  Section: Cursor Position Details
   ###
 
   # Public: Identifies if the cursor is surrounded by whitespace.
@@ -412,7 +412,7 @@ class Cursor extends Model
       @setBufferPosition(position)
 
   ###
-  Section: Retrieving Positions and Ranges of local boundaries
+  Section: Local Positions and Ranges
   ###
 
   # Public: Retrieves the buffer position of where the current word starts.

src/decoration.coffee

@@ -59,6 +59,19 @@ class Decoration
 
     @markerDestroyDisposable = @marker.onDidDestroy => @destroy()
 
+  # Essential: Destroy this marker.
+  #
+  # If you own the marker, you should use {Marker::destroy} which will destroy
+  # this decoration.
+  destroy: ->
+    return if @destroyed
+    @markerDestroyDisposable.dispose()
+    @markerDestroyDisposable = null
+    @destroyed = true
+    @emit 'destroyed'
+    @emitter.emit 'did-destroy'
+    @emitter.dispose()
+
   ###
   Section: Event Subscription
   ###
@@ -83,7 +96,7 @@ class Decoration
     @emitter.on 'did-destroy', callback
 
   ###
-  Section: Methods
+  Section: Decoration Details
   ###
 
   # Essential: An id unique across all {Decoration} objects
@@ -102,6 +115,10 @@ class Decoration
   isType: (type) ->
     Decoration.isType(@properties, type)
 
+  ###
+  Section: Properties
+  ###
+
   # Essential: Returns the {Decoration}'s properties.
   getProperties: ->
     @properties
@@ -129,18 +146,9 @@ class Decoration
     Grim.deprecate 'Use Decoration::setProperties instead'
     @setProperties(newProperties)
 
-  # Essential: Destroy this marker.
-  #
-  # If you own the marker, you should use {Marker::destroy} which will destroy
-  # this decoration.
-  destroy: ->
-    return if @destroyed
-    @markerDestroyDisposable.dispose()
-    @markerDestroyDisposable = null
-    @destroyed = true
-    @emit 'destroyed'
-    @emitter.emit 'did-destroy'
-    @emitter.dispose()
+  ###
+  Section: Private methods
+  ###
 
   matchesPattern: (decorationPattern) ->
     return false unless decorationPattern?

src/git.coffee

@@ -151,7 +151,7 @@ class Git
     EmitterMixin::on.apply(this, arguments)
 
   ###
-  Section: Repository Data
+  Section: Repository Details
   ###
 
   # Public: Returns the {String} path of the repository.

src/marker.coffee

@@ -12,7 +12,7 @@ Grim = require 'grim'
 #
 # ### Marker Creation
 #
-# You will use {Editor::markBufferRange} rather than creating Markers directly.
+# Use {Editor::markBufferRange} rather than creating Markers directly.
 #
 # ### Head and Tail
 #
@@ -128,7 +128,7 @@ class Marker
     EmitterMixin::on.apply(this, arguments)
 
   ###
-  Section: Marker Metadata
+  Section: Marker Details
   ###
 
   # Essential: Returns a {Boolean} indicating whether the marker is valid. Markers can be
@@ -143,11 +143,11 @@ class Marker
   isDestroyed: ->
     @bufferMarker.isDestroyed()
 
-  # Extended: Returns a {Boolean} indicating whether the head precedes the tail.
+  # Essential: Returns a {Boolean} indicating whether the head precedes the tail.
   isReversed: ->
     @bufferMarker.isReversed()
 
-  # Extended: Get the invalidation strategy for this marker.
+  # Essential: Get the invalidation strategy for this marker.
   #
   # Valid values include: `never`, `surround`, `overlap`, `inside`, and `touch`.
   #
@@ -155,7 +155,7 @@ class Marker
   getInvalidationStrategy: ->
     @bufferMarker.getInvalidationStrategy()
 
-  # Extended: Returns an {Object} containing any custom properties associated with
+  # Essential: Returns an {Object} containing any custom properties associated with
   # the marker.
   getProperties: ->
     @bufferMarker.getProperties()
@@ -163,7 +163,7 @@ class Marker
     deprecate 'Use Marker::getProperties instead'
     @getProperties()
 
-  # Extended: Merges an {Object} containing new properties into the marker's
+  # Essential: Merges an {Object} containing new properties into the marker's
   # existing properties.
   #
   # * `properties` {Object}

src/pane-view.coffee

@@ -6,7 +6,7 @@ PropertyAccessors = require 'property-accessors'
 
 Pane = require './pane'
 
-# Extended: A container which can contains multiple items to be switched between.
+# A container which can contains multiple items to be switched between.
 #
 # Items can be almost anything however most commonly they're {EditorView}s.
 #

src/workspace-view.coffee

@@ -20,7 +20,7 @@ atom.commands.add '.workspace',
   'window:decrease-font-size': -> @getModel().decreaseFontSize()
   'window:reset-font-size': -> @getModel().resetFontSize()
 
-# Essential: The top-level view for the entire window. An instance of this class is
+# Extended: 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
@@ -303,16 +303,16 @@ class WorkspaceView extends View
   # Focus the next pane by id.
   focusNextPaneView: -> @model.activateNextPane()
 
-  # Essential: Focus the pane directly above the active pane.
+  # Focus the pane directly above the active pane.
   focusPaneViewAbove: -> @panes.focusPaneViewAbove()
 
-  # Essential: Focus the pane directly below the active pane.
+  # Focus the pane directly below the active pane.
   focusPaneViewBelow: -> @panes.focusPaneViewBelow()
 
-  # Essential: Focus the pane directly to the left of the active pane.
+  # Focus the pane directly to the left of the active pane.
   focusPaneViewOnLeft: -> @panes.focusPaneViewOnLeft()
 
-  # Essential: Focus the pane directly to the right of the active pane.
+  # Focus the pane directly to the right of the active pane.
   focusPaneViewOnRight: -> @panes.focusPaneViewOnRight()
 
   ###

src/workspace.coffee

@@ -103,6 +103,25 @@ class Workspace extends Model
     callback(textEditor) for textEditor in @getTextEditors()
     @onDidAddTextEditor ({textEditor}) -> callback(textEditor)
 
+  # Essential: Invoke the given callback with all current and future panes items in
+  # the workspace.
+  #
+  # * `callback` {Function} to be called with current and future pane items.
+  #   * `item` An item that is present in {::getPaneItems} at the time of
+  #      subscription or that is added at some later time.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  observePaneItems: (callback) -> @paneContainer.observePaneItems(callback)
+
+  # Essential: Invoke the given callback when the active pane item changes.
+  #
+  # * `callback` {Function} to be called when the active pane item changes.
+  #   * `event` {Object} with the following keys:
+  #     * `activeItem` The active pane item.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  onDidChangeActivePaneItem: (callback) -> @paneContainer.onDidChangeActivePaneItem(callback)
+
   # Essential: Invoke the given callback whenever an item is opened. Unlike
   # {::onDidAddPaneItem}, observers will be notified for items that are already
   # present in the workspace when they are reopened.
@@ -167,25 +186,6 @@ class Workspace extends Model
   # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidAddPaneItem: (callback) -> @paneContainer.onDidAddPaneItem(callback)
 
-  # Extended: Invoke the given callback when the active pane item changes.
-  #
-  # * `callback` {Function} to be called when the active pane item changes.
-  #   * `event` {Object} with the following keys:
-  #     * `activeItem` The active pane item.
-  #
-  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
-  onDidChangeActivePaneItem: (callback) -> @paneContainer.onDidChangeActivePaneItem(callback)
-
-  # Extended: Invoke the given callback with all current and future panes items in
-  # the workspace.
-  #
-  # * `callback` {Function} to be called with current and future pane items.
-  #   * `item` An item that is present in {::getPaneItems} at the time of
-  #      subscription or that is added at some later time.
-  #
-  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
-  observePaneItems: (callback) -> @paneContainer.observePaneItems(callback)
-
   # Extended: Invoke the given callback when a text editor is added to the
   # workspace.
   #
@@ -323,7 +323,7 @@ class Workspace extends Model
       .catch (error) ->
         console.error(error.stack ? error)
 
-  # Extended: Asynchronously reopens the last-closed item's URI if it hasn't already been
+  # 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
@@ -339,7 +339,9 @@ class Workspace extends Model
     if uri = @destroyedItemUris.pop()
       @openSync(uri)
 
-  # Extended: Register an opener for a uri.
+  # TODO: make ::registerOpener() return a disposable
+
+  # Public: Register an opener for a uri.
   #
   # An {Editor} will be used if no openers return a value.
   #
@@ -355,7 +357,7 @@ class Workspace extends Model
   registerOpener: (opener) ->
     @openers.push(opener)
 
-  # Extended: Unregister an opener registered with {::registerOpener}.
+  # Unregister an opener registered with {::registerOpener}.
   unregisterOpener: (opener) ->
     _.remove(@openers, opener)
 
@@ -396,7 +398,7 @@ class Workspace extends Model
   getActiveEditor: ->
     @activePane?.getActiveEditor()
 
-  # Extended: Save all pane items.
+  # Save all pane items.
   saveAll: ->
     @paneContainer.saveAll()