From fac979f71d2cd2396ffb8d1246d70d466f074909 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 11:16:23 +0300
Subject: [PATCH 01/19] :memo: Update docs for TextEditor::addGutter

TextEditor::addGutter should be called directly.
---
 src/gutter-container.coffee | 8 --------
 src/text-editor.coffee      | 8 +++++++-
 2 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/src/gutter-container.coffee b/src/gutter-container.coffee
index 4fa7c61fb..bc8ce4246 100644
--- a/src/gutter-container.coffee
+++ b/src/gutter-container.coffee
@@ -21,14 +21,6 @@ class GutterContainer
     @gutters = []
     @emitter.dispose()
 
-  # Creates and returns a {Gutter}.
-  # * `options` An {Object} with the following fields:
-  #   * `name` (required) A unique {String} to identify this gutter.
-  #   * `priority` (optional) A {Number} that determines stacking order between
-  #       gutters. Lower priority items are forced closer to the edges of the
-  #       window. (default: -100)
-  #   * `visible` (optional) {Boolean} specifying whether the gutter is visible
-  #       initially after being created. (default: true)
   addGutter: (options) ->
     options = options ? {}
     gutterName = options.name
diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index 5f6408c30..2a69e8a10 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -515,7 +515,13 @@ class TextEditor extends Model
     @emitter.on 'did-change-line-number-gutter-visible', callback
 
   # Public: Creates and returns a {Gutter}.
-  # See {GutterContainer::addGutter} for more details.
+  # * `options` An {Object} with the following fields:
+  #   * `name` (required) A unique {String} to identify this gutter.
+  #   * `priority` (optional) A {Number} that determines stacking order between
+  #       gutters. Lower priority items are forced closer to the edges of the
+  #       window. (default: -100)
+  #   * `visible` (optional) {Boolean} specifying whether the gutter is visible
+  #       initially after being created. (default: true)
   addGutter: (options) ->
     @gutterContainer.addGutter(options)
 

From fbb3bc42326ace82ac4b8e7ec6cef15bc13e33d1 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 11:44:31 +0300
Subject: [PATCH 02/19] :memo: Make Gutter class extended

Gutter is returned from a public method `TextEditor::addGutter`
---
 src/gutter.coffee | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index 0b3b6533b..d3ea16c95 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -1,19 +1,14 @@
 {Emitter} = require 'event-kit'
 
-# Public: This class represents a gutter within a TextEditor.
-
 DefaultPriority = -100
 
+# Extended: Represents a gutter within a {TextEditor}.
+#
+# ### Gutter Creation
+#
+# See {TextEditor::addGutter} for usage.
 module.exports =
 class Gutter
-  # * `gutterContainer` The {GutterContainer} object to which this gutter belongs.
-  # * `options` An {Object} with the following fields:
-  #   * `name` (required) A unique {String} to identify this gutter.
-  #   * `priority` (optional) A {Number} that determines stacking order between
-  #       gutters. Lower priority items are forced closer to the edges of the
-  #       window. (default: -100)
-  #   * `visible` (optional) {Boolean} specifying whether the gutter is visible
-  #       initially after being created. (default: true)
   constructor: (gutterContainer, options) ->
     @gutterContainer = gutterContainer
     @name = options?.name

From bb447099c07a0f1ea5463fe5d213f8288f07dd9c Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 10:44:59 +0300
Subject: [PATCH 03/19] :art: Move Gutter event methods up

Need for generated docs
---
 src/gutter.coffee | 34 +++++++++++++++++-----------------
 1 file changed, 17 insertions(+), 17 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index d3ea16c95..23012b9f1 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -25,6 +25,23 @@ class Gutter
       @emitter.emit 'did-destroy'
       @emitter.dispose()
 
+  # Calls your `callback` when the {Gutter}'s' visibility changes.
+  #
+  # * `callback` {Function}
+  #  * `gutter` The {Gutter} whose visibility changed.
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  onDidChangeVisible: (callback) ->
+    @emitter.on 'did-change-visible', callback
+
+  # Calls your `callback` when the {Gutter} is destroyed
+  #
+  # * `callback` {Function}
+  #
+  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
+  onDidDestroy: (callback) ->
+    @emitter.on 'did-destroy', callback
+
   hide: ->
     if @visible
       @visible = false
@@ -47,20 +64,3 @@ class Gutter
   # Returns a {Decoration} object.
   decorateMarker: (marker, options) ->
     @gutterContainer.addGutterDecoration(this, marker, options)
-
-  # Calls your `callback` when the {Gutter}'s' visibility changes.
-  #
-  # * `callback` {Function}
-  #  * `gutter` The {Gutter} whose visibility changed.
-  #
-  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
-  onDidChangeVisible: (callback) ->
-    @emitter.on 'did-change-visible', callback
-
-  # Calls your `callback` when the {Gutter} is destroyed
-  #
-  # * `callback` {Function}
-  #
-  # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
-  onDidDestroy: (callback) ->
-    @emitter.on 'did-destroy', callback

From a5edd69ec33bba8e4a73d3afafc5c40fb280a590 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 10:46:17 +0300
Subject: [PATCH 04/19] :memo: Update docs for Gutter events

---
 src/gutter.coffee | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index 23012b9f1..90e5feb29 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -25,16 +25,20 @@ class Gutter
       @emitter.emit 'did-destroy'
       @emitter.dispose()
 
-  # Calls your `callback` when the {Gutter}'s' visibility changes.
+  ###
+  Section: Event Subscription
+  ###
+
+  # Public: Calls your `callback` when the gutter's visibility changes.
   #
   # * `callback` {Function}
-  #  * `gutter` The {Gutter} whose visibility changed.
+  #  * `gutter` The gutter whose visibility changed.
   #
   # Returns a {Disposable} on which `.dispose()` can be called to unsubscribe.
   onDidChangeVisible: (callback) ->
     @emitter.on 'did-change-visible', callback
 
-  # Calls your `callback` when the {Gutter} is destroyed
+  # Public: Calls your `callback` when the gutter is destroyed.
   #
   # * `callback` {Function}
   #

From 150300b63e20a2415ce9483514533a5ed884c49b Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 10:46:50 +0300
Subject: [PATCH 05/19] :memo: Make Gutter visibility methods public

---
 src/gutter.coffee | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index 90e5feb29..adcad21be 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -46,16 +46,23 @@ class Gutter
   onDidDestroy: (callback) ->
     @emitter.on 'did-destroy', callback
 
+  ###
+  Section: Visibility
+  ###
+
+  # Public: Hide the gutter.
   hide: ->
     if @visible
       @visible = false
       @emitter.emit 'did-change-visible', this
 
+  # Public: Show the gutter.
   show: ->
     if not @visible
       @visible = true
       @emitter.emit 'did-change-visible', this
 
+  # Public: Returns the visibility of the gutter.
   isVisible: ->
     @visible
 

From 71c9a4afe75212bfe413ff14b5490c6f2044f34e Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 10:47:51 +0300
Subject: [PATCH 06/19] :memo: Add docs for Gutter::destroy

---
 src/gutter.coffee | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index adcad21be..3a98472d2 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -17,6 +17,11 @@ class Gutter
 
     @emitter = new Emitter
 
+  ###
+  Section: Gutter Destruction
+  ###
+
+  # Public: Destroys the gutter.
   destroy: ->
     if @name is 'line-number'
       throw new Error('The line-number gutter cannot be destroyed.')

From 5f1c227febaab3e5a6ac43af092ae1319cd3b7a8 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 11:24:01 +0300
Subject: [PATCH 07/19] :memo: Make Gutter event methods essential

---
 src/text-editor.coffee | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index 2a69e8a10..ab38d2df4 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -533,7 +533,7 @@ class TextEditor extends Model
   gutterWithName: (name) ->
     @gutterContainer.gutterWithName(name)
 
-  # Calls your `callback` when a {Gutter} is added to the editor.
+  # Essential: Calls your `callback` when a {Gutter} is added to the editor.
   # Immediately calls your callback for each existing gutter.
   #
   # * `callback` {Function}
@@ -543,7 +543,7 @@ class TextEditor extends Model
   observeGutters: (callback) ->
     @gutterContainer.observeGutters callback
 
-  # Calls your `callback` when a {Gutter} is added to the editor.
+  # Essential: Calls your `callback` when a {Gutter} is added to the editor.
   #
   # * `callback` {Function}
   #   * `gutter` {Gutter} that was added.
@@ -552,7 +552,7 @@ class TextEditor extends Model
   onDidAddGutter: (callback) ->
     @gutterContainer.onDidAddGutter callback
 
-  # Calls your `callback` when a {Gutter} is removed from the editor.
+  # Essential: Calls your `callback` when a {Gutter} is removed from the editor.
   #
   # * `callback` {Function}
   #   * `name` The name of the {Gutter} that was removed.

From 559251a1c82edf3296dc92b07379a828700c0152 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 11:19:21 +0300
Subject: [PATCH 08/19] :art: Add section for Gutter methods

Need for generated docs
---
 src/text-editor.coffee | 42 +++++++++++++++++++++++-------------------
 1 file changed, 23 insertions(+), 19 deletions(-)

diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index ab38d2df4..083aef59c 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -514,25 +514,6 @@ class TextEditor extends Model
   onDidChangeLineNumberGutterVisible: (callback) ->
     @emitter.on 'did-change-line-number-gutter-visible', callback
 
-  # Public: Creates and returns a {Gutter}.
-  # * `options` An {Object} with the following fields:
-  #   * `name` (required) A unique {String} to identify this gutter.
-  #   * `priority` (optional) A {Number} that determines stacking order between
-  #       gutters. Lower priority items are forced closer to the edges of the
-  #       window. (default: -100)
-  #   * `visible` (optional) {Boolean} specifying whether the gutter is visible
-  #       initially after being created. (default: true)
-  addGutter: (options) ->
-    @gutterContainer.addGutter(options)
-
-  # Public: Returns the {Array} of all gutters on this editor.
-  getGutters: ->
-    @gutterContainer.getGutters()
-
-  # Public: Returns the {Gutter} with the given name, or null if it doesn't exist.
-  gutterWithName: (name) ->
-    @gutterContainer.gutterWithName(name)
-
   # Essential: Calls your `callback` when a {Gutter} is added to the editor.
   # Immediately calls your callback for each existing gutter.
   #
@@ -2840,6 +2821,29 @@ class TextEditor extends Model
   outermostFoldsInBufferRowRange: (startRow, endRow) ->
     @displayBuffer.outermostFoldsInBufferRowRange(startRow, endRow)
 
+  ###
+  Section: Gutters
+  ###
+
+  # Public: Creates and returns a {Gutter}.
+  # * `options` An {Object} with the following fields:
+  #   * `name` (required) A unique {String} to identify this gutter.
+  #   * `priority` (optional) A {Number} that determines stacking order between
+  #       gutters. Lower priority items are forced closer to the edges of the
+  #       window. (default: -100)
+  #   * `visible` (optional) {Boolean} specifying whether the gutter is visible
+  #       initially after being created. (default: true)
+  addGutter: (options) ->
+    @gutterContainer.addGutter(options)
+
+  # Public: Returns the {Array} of all gutters on this editor.
+  getGutters: ->
+    @gutterContainer.getGutters()
+
+  # Public: Returns the gutter with the given name, or null if it doesn't exist.
+  gutterWithName: (name) ->
+    @gutterContainer.gutterWithName(name)
+
   ###
   Section: Scrolling the TextEditor
   ###

From 1f259a5583523d037032b91a8f34fa922543c9dd Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 10:52:00 +0300
Subject: [PATCH 09/19] :memo: Update docs for TextEditor::decorateMarker

Decorations of `type: 'gutter'` have been renamed to `type: 'line-number'`
---
 src/text-editor.coffee | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index 083aef59c..481b939e4 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -1279,7 +1279,7 @@ class TextEditor extends Model
   #
   # * __line__: Adds your CSS `class` to the line nodes within the range
   #     marked by the marker
-  # * __gutter__: Adds your CSS `class` to the line number nodes within the
+  # * __line-number__: Adds your CSS `class` to the line number nodes within the
   #     range marked by the marker
   # * __highlight__: Adds a new highlight div to the editor surrounding the
   #     range marked by the marker. When the user selects text, the selection is
@@ -1297,9 +1297,9 @@ class TextEditor extends Model
   # * `marker` A {Marker} you want this decoration to follow.
   # * `decorationParams` An {Object} representing the decoration e.g.
   #   `{type: 'line-number', class: 'linter-error'}`
-  #   * `type` There are a few supported decoration types: `gutter`, `line`,
+  #   * `type` There are a few supported decoration types: `line-number`, `line`,
   #     `highlight`, and `overlay`. The behavior of the types are as follows:
-  #     * `gutter` Adds the given `class` to the line numbers overlapping the
+  #     * `line-number` Adds the given `class` to the line numbers overlapping the
   #       rows spanned by the marker.
   #     * `line` Adds the given `class` to the lines overlapping the rows
   #        spanned by the marker.
@@ -1311,14 +1311,14 @@ class TextEditor extends Model
   #   * `class` This CSS class will be applied to the decorated line number,
   #     line, highlight, or overlay.
   #   * `onlyHead` (optional) If `true`, the decoration will only be applied to
-  #     the head of the marker. Only applicable to the `line` and `gutter`
+  #     the head of the marker. Only applicable to the `line` and `line-number`
   #     types.
   #   * `onlyEmpty` (optional) If `true`, the decoration will only be applied if
   #     the associated marker is empty. Only applicable to the `line` and
-  #     `gutter` types.
+  #     `line-number` types.
   #   * `onlyNonEmpty` (optional) If `true`, the decoration will only be applied
   #     if the associated marker is non-empty.  Only applicable to the `line`
-  #     and gutter types.
+  #     and `line-number` types.
   #   * `position` (optional) Only applicable to decorations of type `overlay`,
   #     controls where the overlay view is positioned relative to the marker.
   #     Values can be `'head'` (the default), or `'tail'`.

From 6076cef1f239f84ecda07b2975b5ec0adc595966 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 10:53:06 +0300
Subject: [PATCH 10/19] :memo: Remove `gutterName` argument from
 TextEditor::decorateMarker

Decorations of `type: 'gutter'` is deprecated. Use `Gutter::decorateMarker` to
create decoration for custom gutter.
---
 src/text-editor.coffee | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index 481b939e4..4b7c85d21 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -1322,8 +1322,6 @@ class TextEditor extends Model
   #   * `position` (optional) Only applicable to decorations of type `overlay`,
   #     controls where the overlay view is positioned relative to the marker.
   #     Values can be `'head'` (the default), or `'tail'`.
-  #   * `gutterName` (optional) Only applicable to the `gutter` type. If provided,
-  #     the decoration will be applied to the gutter with the specified name.
   #
   # Returns a {Decoration} object
   decorateMarker: (marker, decorationParams) ->

From df2fed2474300bc4e87caa9f5a90723b13b67681 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 11:48:12 +0300
Subject: [PATCH 11/19] :memo: Update docs for Gutter::decorateMarker

Docs from TextEditor::decorateMarker related to Gutter
---
 src/gutter.coffee | 22 ++++++++++++++++------
 1 file changed, 16 insertions(+), 6 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index 3a98472d2..434b9003c 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -71,12 +71,22 @@ class Gutter
   isVisible: ->
     @visible
 
-  # * `marker` (required) A Marker object.
-  # * `options` (optional) An object with the following fields:
-  #   * `class` (optional)
-  #   * `item` (optional) A model {Object} with a corresponding view registered,
-  #     or an {HTMLElement}.
+  # Public: Adds a decoration that tracks a {Marker}. When the marker moves,
+  # is invalidated, or is destroyed, the decoration will be updated to reflect
+  # the marker's state.
   #
-  # Returns a {Decoration} object.
+  # ## Arguments
+  #
+  # * `marker` A {Marker} you want this decoration to follow.
+  # * `decorationParams` An {Object} representing the decoration
+  #   * `class` This CSS class will be applied to the decorated line number.
+  #   * `onlyHead` (optional) If `true`, the decoration will only be applied to
+  #     the head of the marker.
+  #   * `onlyEmpty` (optional) If `true`, the decoration will only be applied if
+  #     the associated marker is empty.
+  #   * `onlyNonEmpty` (optional) If `true`, the decoration will only be applied
+  #     if the associated marker is non-empty.
+  #
+  # Returns a {Decoration} object
   decorateMarker: (marker, options) ->
     @gutterContainer.addGutterDecoration(this, marker, options)

From 93fba6a334cd2e384e4e0127e758e8b2e7a3bf97 Mon Sep 17 00:00:00 2001
From: Maxim Sokolov <maxim0xff@gmail.com>
Date: Wed, 26 Aug 2015 11:37:19 +0300
Subject: [PATCH 12/19] :memo: Remove redundant docs

GutterContainer class shouldn't be public or extended.
---
 src/gutter-container.coffee | 11 -----------
 1 file changed, 11 deletions(-)

diff --git a/src/gutter-container.coffee b/src/gutter-container.coffee
index bc8ce4246..084e1e1ad 100644
--- a/src/gutter-container.coffee
+++ b/src/gutter-container.coffee
@@ -1,12 +1,8 @@
 {Emitter} = require 'event-kit'
 Gutter = require './gutter'
 
-# This class encapsulates the logic for adding and modifying a set of gutters.
-
 module.exports =
 class GutterContainer
-
-  # * `textEditor` The {TextEditor} to which this {GutterContainer} belongs.
   constructor: (textEditor) ->
     @gutters = []
     @textEditor = textEditor
@@ -51,20 +47,13 @@ class GutterContainer
       if gutter.name is name then return gutter
     null
 
-  ###
-  Section: Event Subscription
-  ###
-
-  # See {TextEditor::observeGutters} for details.
   observeGutters: (callback) ->
     callback(gutter) for gutter in @getGutters()
     @onDidAddGutter callback
 
-  # See {TextEditor::onDidAddGutter} for details.
   onDidAddGutter: (callback) ->
     @emitter.on 'did-add-gutter', callback
 
-  # See {TextEditor::onDidRemoveGutter} for details.
   onDidRemoveGutter: (callback) ->
     @emitter.on 'did-remove-gutter', callback
 

From ba7af0b9cd3fe5f9c01bdc3a15628749e675740b Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Fri, 28 Aug 2015 09:39:03 -0600
Subject: [PATCH 13/19] Remove arguments subheading

---
 src/text-editor.coffee | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index 4b7c85d21..e5cb0dabe 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -1292,8 +1292,6 @@ class TextEditor extends Model
   #     </div>
   #     ```
   #
-  # ## Arguments
-  #
   # * `marker` A {Marker} you want this decoration to follow.
   # * `decorationParams` An {Object} representing the decoration e.g.
   #   `{type: 'line-number', class: 'linter-error'}`

From bd4f5ba544f6888afa95b44ff55db735dab8c954 Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Fri, 28 Aug 2015 09:39:24 -0600
Subject: [PATCH 14/19] Replace Public with Essential
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Still not sure about the value of this distinction, but let’s blend in.
---
 src/text-editor.coffee | 32 ++++++++++++++++----------------
 1 file changed, 16 insertions(+), 16 deletions(-)

diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index e5cb0dabe..39da338f3 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -14,7 +14,7 @@ TextMateScopeSelector = require('first-mate').ScopeSelector
 {Directory} = require "pathwatcher"
 GutterContainer = require './gutter-container'
 
-# Public: This class represents all essential editing state for a single
+# Essential: This class represents all essential editing state for a single
 # {TextBuffer}, including cursor and selection positions, folds, and soft wraps.
 # If you're manipulating the state of an editor, use this class. If you're
 # interested in the visual appearance of editors, use {TextEditorView} instead.
@@ -341,7 +341,7 @@ class TextEditor extends Model
   onDidInsertText: (callback) ->
     @emitter.on 'did-insert-text', callback
 
-  # Public: Invoke the given callback after the buffer is saved to disk.
+  # Essential: Invoke the given callback after the buffer is saved to disk.
   #
   # * `callback` {Function} to be called after the buffer is saved.
   #   * `event` {Object} with the following keys:
@@ -351,7 +351,7 @@ class TextEditor extends Model
   onDidSave: (callback) ->
     @getBuffer().onDidSave(callback)
 
-  # Public: Invoke the given callback when the editor is destroyed.
+  # Essential: Invoke the given callback when the editor is destroyed.
   #
   # * `callback` {Function} to be called when the editor is destroyed.
   #
@@ -470,7 +470,7 @@ class TextEditor extends Model
   onDidUpdateMarkers: (callback) ->
     @displayBuffer.onDidUpdateMarkers(callback)
 
-  # Public: Retrieves the current {TextBuffer}.
+  # Essential: Retrieves the current {TextBuffer}.
   getBuffer: -> @buffer
 
   # Retrieves the current buffer's URI.
@@ -616,7 +616,7 @@ class TextEditor extends Model
   # See {TextBuffer::save} for more details.
   save: -> @buffer.save(backup: atom.config.get('editor.backUpBeforeSaving'))
 
-  # Public: Saves the editor's text buffer as the given path.
+  # Essential: Saves the editor's text buffer as the given path.
   #
   # See {TextBuffer::saveAs} for more details.
   #
@@ -729,7 +729,7 @@ class TextEditor extends Model
   # {Delegates to: TextBuffer.getEndPosition}
   getEofBufferPosition: -> @buffer.getEndPosition()
 
-  # Public: Get the {Range} of the paragraph surrounding the most recently added
+  # Essential: Get the {Range} of the paragraph surrounding the most recently added
   # cursor.
   #
   # Returns a {Range}.
@@ -1328,7 +1328,7 @@ class TextEditor extends Model
       decorationParams.type = 'line-number'
     @displayBuffer.decorateMarker(marker, decorationParams)
 
-  # Public: Get all the decorations within a screen row range.
+  # Essential: Get all the decorations within a screen row range.
   #
   # * `startScreenRow` the {Number} beginning screen row
   # * `endScreenRow` the {Number} end screen row (inclusive)
@@ -2308,7 +2308,7 @@ class TextEditor extends Model
   #     * `replace` Call this {Function} with a {String} to replace the match.
   scan: (regex, iterator) -> @buffer.scan(regex, iterator)
 
-  # Public: Scan regular expression matches in a given range, calling the given
+  # Essential: Scan regular expression matches in a given range, calling the given
   # iterator function on each match.
   #
   # * `regex` A {RegExp} to search for.
@@ -2322,7 +2322,7 @@ class TextEditor extends Model
   #   * `replace` Call this {Function} with a {String} to replace the match.
   scanInBufferRange: (regex, range, iterator) -> @buffer.scanInRange(regex, range, iterator)
 
-  # Public: Scan regular expression matches in a given range in reverse order,
+  # Essential: Scan regular expression matches in a given range in reverse order,
   # calling the given iterator function on each match.
   #
   # * `regex` A {RegExp} to search for.
@@ -2434,7 +2434,7 @@ class TextEditor extends Model
   # Returns a {Boolean}.
   toggleSoftWrapped: -> @setSoftWrapped(not @isSoftWrapped())
 
-  # Public: Gets the column at which column will soft wrap
+  # Essential: Gets the column at which column will soft wrap
   getSoftWrapColumn: -> @displayBuffer.getSoftWrapColumn()
 
   ###
@@ -2669,7 +2669,7 @@ class TextEditor extends Model
       @emit('did-insert-text', didInsertEvent) if includeDeprecatedAPIs
       @emitter.emit 'did-insert-text', didInsertEvent
 
-  # Public: For each selection, if the selection is empty, cut all characters
+  # Essential: For each selection, if the selection is empty, cut all characters
   # of the containing line following the cursor. Otherwise cut the selected
   # text.
   cutToEndOfLine: ->
@@ -2821,7 +2821,7 @@ class TextEditor extends Model
   Section: Gutters
   ###
 
-  # Public: Creates and returns a {Gutter}.
+  # Essential: Creates and returns a {Gutter}.
   # * `options` An {Object} with the following fields:
   #   * `name` (required) A unique {String} to identify this gutter.
   #   * `priority` (optional) A {Number} that determines stacking order between
@@ -2832,11 +2832,11 @@ class TextEditor extends Model
   addGutter: (options) ->
     @gutterContainer.addGutter(options)
 
-  # Public: Returns the {Array} of all gutters on this editor.
+  # Essential: Returns the {Array} of all gutters on this editor.
   getGutters: ->
     @gutterContainer.getGutters()
 
-  # Public: Returns the gutter with the given name, or null if it doesn't exist.
+  # Essential: Returns the gutter with the given name, or null if it doesn't exist.
   gutterWithName: (name) ->
     @gutterContainer.gutterWithName(name)
 
@@ -2940,13 +2940,13 @@ class TextEditor extends Model
   Section: TextEditor Rendering
   ###
 
-  # Public: Retrieves the greyed out placeholder of a mini editor.
+  # Essential: Retrieves the greyed out placeholder of a mini editor.
   #
   # Returns a {String}.
   getPlaceholderText: ->
     @placeholderText
 
-  # Public: Set the greyed out placeholder of a mini editor. Placeholder text
+  # Essential: Set the greyed out placeholder of a mini editor. Placeholder text
   # will be displayed when the editor has no content.
   #
   # * `placeholderText` {String} text that is displayed when the editor has no content.

From 313eb9e926690d2926921b82176d34f78bec3264 Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Fri, 28 Aug 2015 09:41:13 -0600
Subject: [PATCH 15/19] :art:

---
 src/gutter.coffee | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index 434b9003c..e564bc898 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -4,9 +4,7 @@ DefaultPriority = -100
 
 # Extended: Represents a gutter within a {TextEditor}.
 #
-# ### Gutter Creation
-#
-# See {TextEditor::addGutter} for usage.
+# See {TextEditor::addGutter} for information on creating a gutter.
 module.exports =
 class Gutter
   constructor: (gutterContainer, options) ->

From 1160c571a75b76d3b6d8ec0182f2f9d602a6175b Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Fri, 28 Aug 2015 09:41:23 -0600
Subject: [PATCH 16/19] Public -> Essential

---
 src/gutter.coffee | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index e564bc898..eb93ac25e 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -19,7 +19,7 @@ class Gutter
   Section: Gutter Destruction
   ###
 
-  # Public: Destroys the gutter.
+  # Essential: Destroys the gutter.
   destroy: ->
     if @name is 'line-number'
       throw new Error('The line-number gutter cannot be destroyed.')
@@ -32,7 +32,7 @@ class Gutter
   Section: Event Subscription
   ###
 
-  # Public: Calls your `callback` when the gutter's visibility changes.
+  # Essential: Calls your `callback` when the gutter's visibility changes.
   #
   # * `callback` {Function}
   #  * `gutter` The gutter whose visibility changed.
@@ -41,7 +41,7 @@ class Gutter
   onDidChangeVisible: (callback) ->
     @emitter.on 'did-change-visible', callback
 
-  # Public: Calls your `callback` when the gutter is destroyed.
+  # Essential: Calls your `callback` when the gutter is destroyed.
   #
   # * `callback` {Function}
   #
@@ -53,23 +53,23 @@ class Gutter
   Section: Visibility
   ###
 
-  # Public: Hide the gutter.
+  # Essential: Hide the gutter.
   hide: ->
     if @visible
       @visible = false
       @emitter.emit 'did-change-visible', this
 
-  # Public: Show the gutter.
+  # Essential: Show the gutter.
   show: ->
     if not @visible
       @visible = true
       @emitter.emit 'did-change-visible', this
 
-  # Public: Returns the visibility of the gutter.
+  # Essential: Returns the visibility of the gutter.
   isVisible: ->
     @visible
 
-  # Public: Adds a decoration that tracks a {Marker}. When the marker moves,
+  # Essential: Adds a decoration that tracks a {Marker}. When the marker moves,
   # is invalidated, or is destroyed, the decoration will be updated to reflect
   # the marker's state.
   #

From f2a017d0136ba3717bdc5261279849824d706b8b Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Fri, 28 Aug 2015 09:42:39 -0600
Subject: [PATCH 17/19] Nix arguments

---
 src/gutter.coffee | 2 --
 1 file changed, 2 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index eb93ac25e..0c09cdf3e 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -73,8 +73,6 @@ class Gutter
   # is invalidated, or is destroyed, the decoration will be updated to reflect
   # the marker's state.
   #
-  # ## Arguments
-  #
   # * `marker` A {Marker} you want this decoration to follow.
   # * `decorationParams` An {Object} representing the decoration
   #   * `class` This CSS class will be applied to the decorated line number.

From 1dac9eb80168b8024329a2ba03b22dcdb57980f9 Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Fri, 28 Aug 2015 09:42:46 -0600
Subject: [PATCH 18/19] Use imperative voice

---
 src/gutter.coffee | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/gutter.coffee b/src/gutter.coffee
index 0c09cdf3e..160036e3e 100644
--- a/src/gutter.coffee
+++ b/src/gutter.coffee
@@ -65,11 +65,13 @@ class Gutter
       @visible = true
       @emitter.emit 'did-change-visible', this
 
-  # Essential: Returns the visibility of the gutter.
+  # Essential: Determine whether the gutter is visible.
+  #
+  # Returns a {Boolean}.
   isVisible: ->
     @visible
 
-  # Essential: Adds a decoration that tracks a {Marker}. When the marker moves,
+  # Essential: Add a decoration that tracks a {Marker}. When the marker moves,
   # is invalidated, or is destroyed, the decoration will be updated to reflect
   # the marker's state.
   #

From 0a87dad74762b6e6b6b1d21930811d9077d8d6e5 Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Fri, 28 Aug 2015 09:46:18 -0600
Subject: [PATCH 19/19] :art:

---
 src/text-editor.coffee | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/src/text-editor.coffee b/src/text-editor.coffee
index 39da338f3..b8c2a76fb 100644
--- a/src/text-editor.coffee
+++ b/src/text-editor.coffee
@@ -2821,7 +2821,8 @@ class TextEditor extends Model
   Section: Gutters
   ###
 
-  # Essential: Creates and returns a {Gutter}.
+  # Essential: Add a custom {Gutter}.
+  #
   # * `options` An {Object} with the following fields:
   #   * `name` (required) A unique {String} to identify this gutter.
   #   * `priority` (optional) A {Number} that determines stacking order between
@@ -2829,14 +2830,20 @@ class TextEditor extends Model
   #       window. (default: -100)
   #   * `visible` (optional) {Boolean} specifying whether the gutter is visible
   #       initially after being created. (default: true)
+  #
+  # Returns the newly-created {Gutter}.
   addGutter: (options) ->
     @gutterContainer.addGutter(options)
 
-  # Essential: Returns the {Array} of all gutters on this editor.
+  # Essential: Get this editor's gutters.
+  #
+  # Returns an {Array} of {Gutter}s.
   getGutters: ->
     @gutterContainer.getGutters()
 
-  # Essential: Returns the gutter with the given name, or null if it doesn't exist.
+  # Essential: Get the gutter with the given name.
+  #
+  # Returns a {Gutter}, or `null` if no gutter exists for the given name.
   gutterWithName: (name) ->
     @gutterContainer.gutterWithName(name)