📝 Convert Cursor Docs

src/cursor.coffee

@@ -2,11 +2,36 @@
 {Model} = require 'theorist'
 _ = require 'underscore-plus'
 
-# Public: The `Cursor` class represents the little blinking line identifying
+# Extended: The `Cursor` class represents the little blinking line identifying
 # where text can be inserted.
 #
 # Cursors belong to {Editor}s and have some metadata attached in the form
 # of a {Marker}.
+#
+# ## Events
+#
+# ### moved
+#
+# Extended: Emit when a cursor has been moved. If there are multiple cursors,
+# it will be emit for each cursor.
+#
+# * `event` {Object}
+#   * `oldBufferPosition` {Point}
+#   * `oldScreenPosition` {Point}
+#   * `newBufferPosition` {Point}
+#   * `newScreenPosition` {Point}
+#   * `textChanged` {Boolean}
+#
+# ### destroyed
+#
+# Extended: Emit when the cursor is destroyed
+#
+# ### visibility-changed
+#
+# Extended: Emit when the Cursor is hidden or shown
+#
+# * `visible` {Boolean} true when cursor is visible
+#
 module.exports =
 class Cursor extends Model
   screenPosition: null
@@ -63,11 +88,10 @@ class Cursor extends Model
 
   # Public: Moves a cursor to a given screen position.
   #
-  # screenPosition - An {Array} of two numbers: the screen row, and the screen
-  #                  column.
-  # options - An {Object} with the following keys:
-  #   :autoscroll - A Boolean which, if `true`, scrolls the {Editor} to wherever
-  #                 the cursor moves to.
+  # * `screenPosition` {Array} of two numbers: the screen row, and the screen column.
+  # * `options` (optional) {Object} with the following keys:
+  #   * `autoscroll` A Boolean which, if `true`, scrolls the {Editor} to wherever
+  #     the cursor moves to.
   setScreenPosition: (screenPosition, options={}) ->
     @changePosition options, =>
       @marker.setHeadScreenPosition(screenPosition, options)
@@ -82,11 +106,10 @@ class Cursor extends Model
 
   # Public: Moves a cursor to a given buffer position.
   #
-  # bufferPosition - An {Array} of two numbers: the buffer row, and the buffer
-  #                  column.
-  # options - An {Object} with the following keys:
-  #   :autoscroll - A Boolean which, if `true`, scrolls the {Editor} to wherever
-  #                 the cursor moves to.
+  # * `bufferPosition` {Array} of two numbers: the buffer row, and the buffer column.
+  # * `options` (optional) {Object} with the following keys:
+  #   * `autoscroll` A Boolean which, if `true`, scrolls the {Editor} to wherever
+  #     the cursor moves to.
   setBufferPosition: (bufferPosition, options={}) ->
     @changePosition options, =>
       @marker.setHeadBufferPosition(bufferPosition, options)
@@ -114,10 +137,9 @@ class Cursor extends Model
 
   # Public: Get the RegExp used by the cursor to determine what a "word" is.
   #
-  # options: An optional {Object} with the following keys:
-  #   :includeNonWordCharacters - A {Boolean} indicating whether to include
-  #                               non-word characters in the regex.
-  #                               (default: true)
+  # * `options` (optional) {Object} with the following keys:
+  #   * `includeNonWordCharacters` A {Boolean} indicating whether to include
+  #     non-word characters in the regex. (default: true)
   #
   # Returns a {RegExp}.
   wordRegExp: ({includeNonWordCharacters}={}) ->
@@ -228,9 +250,9 @@ class Cursor extends Model
 
   # Public: Moves the cursor left one screen column.
   #
-  # options - An {Object} with the following keys:
-  #   :moveToEndOfSelection - if true, move to the left of the selection if a
-  #                           selection exists.
+  # * `options` (optional) {Object} with the following keys:
+  #   * `moveToEndOfSelection` if true, move to the left of the selection if a
+  #     selection exists.
   moveLeft: ({moveToEndOfSelection}={}) ->
     range = @marker.getScreenRange()
     if moveToEndOfSelection and not range.isEmpty()
@@ -242,9 +264,9 @@ class Cursor extends Model
 
   # Public: Moves the cursor right one screen column.
   #
-  # options - An {Object} with the following keys:
-  #   :moveToEndOfSelection - if true, move to the right of the selection if a
-  #                           selection exists.
+  # * `options` (optional) {Object} with the following keys:
+  #   * `moveToEndOfSelection` if true, move to the right of the selection if a
+  #     selection exists.
   moveRight: ({moveToEndOfSelection}={}) ->
     range = @marker.getScreenRange()
     if moveToEndOfSelection and not range.isEmpty()
@@ -332,14 +354,14 @@ class Cursor extends Model
 
   # Public: Retrieves the buffer position of where the current word starts.
   #
-  # options - An {Object} with the following keys:
-  #   :wordRegex - A {RegExp} indicating what constitutes a "word"
-  #                (default: {::wordRegExp}).
-  #   :includeNonWordCharacters - A {Boolean} indicating whether to include
-  #                               non-word characters in the default word regex.
-  #                               Has no effect if wordRegex is set.
-  #   :allowPrevious - A {Boolean} indicating whether the beginning of the
-  #                    previous word can be returned.
+  # * `options` (optional) An {Object} with the following keys:
+  #   * `wordRegex` A {RegExp} indicating what constitutes a "word"
+  #     (default: {::wordRegExp}).
+  #   * `includeNonWordCharacters` A {Boolean} indicating whether to include
+  #     non-word characters in the default word regex.
+  #     Has no effect if wordRegex is set.
+  #   * `allowPrevious` A {Boolean} indicating whether the beginning of the
+  #     previous word can be returned.
   #
   # Returns a {Range}.
   getBeginningOfCurrentWordBufferPosition: (options = {}) ->
@@ -407,12 +429,12 @@ class Cursor extends Model
 
   # Public: Retrieves the buffer position of where the current word ends.
   #
-  # options - An {Object} with the following keys:
-  #   :wordRegex - A {RegExp} indicating what constitutes a "word"
-  #                (default: {::wordRegExp})
-  #   :includeNonWordCharacters - A Boolean indicating whether to include
-  #                               non-word characters in the default word regex.
-  #                               Has no effect if wordRegex is set.
+  # * `options` (optional) {Object} with the following keys:
+  #   * `wordRegex` A {RegExp} indicating what constitutes a "word"
+  #      (default: {::wordRegExp})
+  #   * `includeNonWordCharacters` A Boolean indicating whether to include
+  #     non-word characters in the default word regex. Has no effect if
+  #     wordRegex is set.
   #
   # Returns a {Range}.
   getEndOfCurrentWordBufferPosition: (options = {}) ->
@@ -431,11 +453,11 @@ class Cursor extends Model
 
   # Public: Retrieves the buffer position of where the next word starts.
   #
-  # options -
-  #   :wordRegex - A {RegExp} indicating what constitutes a "word"
-  #                (default: {::wordRegExp}).
+  # * `options` (optional) {Object}
+  #   * `wordRegex` A {RegExp} indicating what constitutes a "word"
+  #     (default: {::wordRegExp}).
   #
-  # Returns a {Range}.
+  # Returns a {Range}
   getBeginningOfNextWordBufferPosition: (options = {}) ->
     currentBufferPosition = @getBufferPosition()
     start = if @isInsideWord() then @getEndOfCurrentWordBufferPosition() else currentBufferPosition
@@ -450,9 +472,9 @@ class Cursor extends Model
 
   # Public: Returns the buffer Range occupied by the word located under the cursor.
   #
-  # options -
-  #   :wordRegex - A {RegExp} indicating what constitutes a "word"
-  #                (default: {::wordRegExp}).
+  # * `options` (optional) {Object}
+  #   * `wordRegex` A {RegExp} indicating what constitutes a "word"
+  #     (default: {::wordRegExp}).
   getCurrentWordBufferRange: (options={}) ->
     startOptions = _.extend(_.clone(options), allowPrevious: false)
     endOptions = _.extend(_.clone(options), allowNext: false)
@@ -460,9 +482,9 @@ class Cursor extends Model
 
   # Public: Returns the buffer Range for the current line.
   #
-  # options -
-  #   :includeNewline: - A {Boolean} which controls whether the Range should
-  #                      include the newline.
+  # * `options` (optional) {Object}
+  #   * `includeNewline` A {Boolean} which controls whether the Range should
+  #     include the newline.
   getCurrentLineBufferRange: (options) ->
     @editor.bufferRangeForBufferRow(@getBufferRow(), options)