Reformat Selection comments

src/selection.coffee

@@ -14,8 +14,8 @@ class Selection
   wordwise: false
   needsAutoscroll: null
 
-  ### Internal ###
 
+  # Private:
   constructor: ({@cursor, @marker, @editSession}) ->
     @cursor.selection = this
     @marker.on 'changed', => @screenRangeChanged()
@@ -24,65 +24,62 @@ class Selection
       @editSession.removeSelection(this)
       @trigger 'destroyed' unless @editSession.destroyed
 
+  # Private:
   destroy: ->
     @marker.destroy()
 
+  # Private:
   finalize: ->
     @initialScreenRange = null unless @initialScreenRange?.isEqual(@getScreenRange())
     if @isEmpty()
       @wordwise = false
       @linewise = false
 
+  # Private:
   clearAutoscroll: ->
     @needsAutoscroll = null
 
-  ### Public ###
-
-  # Identifies if the selection is highlighting anything.
-  #
-  # Returns a {Boolean}.
+  # Public: Determines if the selection contains anything.
   isEmpty: ->
     @getBufferRange().isEmpty()
 
-  # Identifies if the ending position of a marker is greater than the starting position.
+  # Public: Determines if the ending position of a marker is greater than the
+  # starting position.
   #
   # This can happen when, for example, you highlight text "up" in a {TextBuffer}.
-  #
-  # Returns a {Boolean}.
   isReversed: ->
     @marker.isReversed()
 
-  # Identifies if the selection is a single line.
-  #
-  # Returns a {Boolean}.
+  # Public: Returns whether the selection is a single line or not.
   isSingleScreenLine: ->
     @getScreenRange().isSingleLine()
 
-  # Retrieves the screen range for the selection.
-  #
-  # Returns a {Range}.
+  # Public: Returns the screen {Range} for the selection.
   getScreenRange: ->
     @marker.getScreenRange()
 
-  # Modifies the screen range for the selection.
+  # Public: Modifies the screen range for the selection.
   #
-  # screenRange - The new {Range} to use
-  # options - A hash of options matching those found in {.setBufferRange}
+  # * screenRange:
+  #   The new {Range} to use
+  # * options:
+  #   + A hash of options matching those found in {.setBufferRange}
   setScreenRange: (screenRange, options) ->
     @setBufferRange(@editSession.bufferRangeForScreenRange(screenRange), options)
 
-  # Retrieves the buffer range for the selection.
-  #
-  # Returns a {Range}.
+  # Public: Returns the buffer {Range} for the selection.
   getBufferRange: ->
     @marker.getBufferRange()
 
-  # Modifies the buffer range for the selection.
+  # Public: Modifies the buffer {Range} for the selection.
   #
-  # screenRange - The new {Range} to select
-  # options - A hash of options with the following keys:
-  #           preserveFolds: if `true`, the fold settings are preserved after the selection moves
-  #           autoscroll: if `true`, the {EditSession} scrolls to the new selection
+  # * screenRange:
+  #   The new {Range} to select
+  # * options
+  #    + preserveFolds:
+  #      if `true`, the fold settings are preserved after the selection moves
+  #    + autoscroll:
+  #      if `true`, the {EditSession} scrolls to the new selection
   setBufferRange: (bufferRange, options={}) ->
     bufferRange = Range.fromObject(bufferRange)
     @needsAutoscroll = options.autoscroll
@@ -92,7 +89,8 @@ class Selection
       @cursor.needsAutoscroll = false if options.autoscroll?
       @marker.setBufferRange(bufferRange, options)
 
-  # Retrieves the starting and ending buffer rows the selection is highlighting.
+  # Public: Returns the starting and ending buffer rows the selection is
+  # highlighting.
   #
   # Returns an {Array} of two {Number}s: the starting row, and the ending row.
   getBufferRowRange: ->
@@ -102,18 +100,16 @@ class Selection
     end = Math.max(start, end - 1) if range.end.column == 0
     [start, end]
 
-  # Retrieves the text in the selection.
-  #
-  # Returns a {String}.
+  # Public: Returns the text in the selection.
   getText: ->
     @editSession.buffer.getTextInRange(@getBufferRange())
 
-  # Clears the selection, moving the marker to move to the head.
+  # Public: Clears the selection, moving the marker to the head.
   clear: ->
     @marker.setAttributes(goalBufferRange: null)
     @marker.clearTail() unless @retainSelection
 
-  # Modifies the selection to mark the current word.
+  # Public: Modifies the selection to encompass the current word.
   #
   # Returns a {Range}.
   selectWord: ->
@@ -124,12 +120,16 @@ class Selection
     @wordwise = true
     @initialScreenRange = @getScreenRange()
 
+  # Public:
+  #
+  # FIXME: I have no idea what this does.
   expandOverWord: ->
     @setBufferRange(@getBufferRange().union(@cursor.getCurrentWordBufferRange()))
 
-  # Selects an entire line in the {TextBuffer}.
+  # Public: Selects an entire line in the buffer.
   #
-  # row - The line {Number} to select (default: the row of the cursor)
+  # * row:
+  #   The line Number to select (default: the row of the cursor)
   selectLine: (row=@cursor.getBufferPosition().row) ->
     range = @editSession.bufferRangeForBufferRow(row, includeNewline: true)
     @setBufferRange(range)
@@ -137,13 +137,18 @@ class Selection
     @wordwise = false
     @initialScreenRange = @getScreenRange()
 
+  # Public:
+  #
+  # FIXME: I have no idea what this does.
   expandOverLine: ->
     range = @getBufferRange().union(@cursor.getCurrentLineBufferRange(includeNewline: true))
     @setBufferRange(range)
 
-  # Selects the text from the current cursor position to a given screen position.
+  # Public: Selects the text from the current cursor position to a given screen
+  # position.
   #
-  # position - An instance of {Point}, with a given `row` and `column`.
+  # * position:
+  #   An instance of {Point}, with a given `row` and `column`.
   selectToScreenPosition: (position) ->
     @modifySelection =>
       if @initialScreenRange
@@ -159,73 +164,83 @@ class Selection
       else if @wordwise
         @expandOverWord()
 
-  # Selects the text from the current cursor position to a given buffer position.
+  # Public: Selects the text from the current cursor position to a given buffer
+  # position.
   #
-  # position - An instance of {Point}, with a given `row` and `column`.
+  # * position:
+  #   An instance of {Point}, with a given `row` and `column`.
   selectToBufferPosition: (position) ->
     @modifySelection => @cursor.setBufferPosition(position)
 
-  # Selects the text one position right of the cursor.
+  # Public: Selects the text one position right of the cursor.
   selectRight: ->
     @modifySelection => @cursor.moveRight()
 
-  # Selects the text one position left of the cursor.
+  # Public: Selects the text one position left of the cursor.
   selectLeft: ->
     @modifySelection => @cursor.moveLeft()
 
-  # Selects all the text one position above the cursor.
+  # Public: Selects all the text one position above the cursor.
   selectUp: ->
     @modifySelection => @cursor.moveUp()
 
-  # Selects all the text one position below the cursor.
+  # Public: Selects all the text one position below the cursor.
   selectDown: ->
     @modifySelection => @cursor.moveDown()
 
-  # Selects all the text from the current cursor position to the top of the buffer.
+  # Public: Selects all the text from the current cursor position to the top of
+  # the buffer.
   selectToTop: ->
     @modifySelection => @cursor.moveToTop()
 
-  # Selects all the text from the current cursor position to the bottom of the buffer.
+  # Public: Selects all the text from the current cursor position to the bottom
+  # of the buffer.
   selectToBottom: ->
     @modifySelection => @cursor.moveToBottom()
 
-  # Selects all the text in the buffer.
+  # Public: Selects all the text in the buffer.
   selectAll: ->
     @setBufferRange(@editSession.buffer.getRange(), autoscroll: false)
 
-  # Selects all the text from the current cursor position to the beginning of the line.
+  # Public: Selects all the text from the current cursor position to the
+  # beginning of the line.
   selectToBeginningOfLine: ->
     @modifySelection => @cursor.moveToBeginningOfLine()
 
-  # Selects all the text from the current cursor position to the first character of the line.
+  # Public: Selects all the text from the current cursor position to the first
+  # character of the line.
   selectToFirstCharacterOfLine: ->
     @modifySelection => @cursor.moveToFirstCharacterOfLine()
 
-  # Selects all the text from the current cursor position to the end of the line.
+  # Public: Selects all the text from the current cursor position to the end of
+  # the line.
   selectToEndOfLine: ->
     @modifySelection => @cursor.moveToEndOfLine()
 
-  # Selects all the text from the current cursor position to the beginning of the word.
+  # Public: Selects all the text from the current cursor position to the
+  # beginning of the word.
   selectToBeginningOfWord: ->
     @modifySelection => @cursor.moveToBeginningOfWord()
 
-  # Selects all the text from the current cursor position to the end of the word.
+  # Public: Selects all the text from the current cursor position to the end of
+  # the word.
   selectToEndOfWord: ->
     @modifySelection => @cursor.moveToEndOfWord()
 
-  # Selects all the text from the current cursor position to the beginning of the next word.
+  # Public: Selects all the text from the current cursor position to the
+  # beginning of the next word.
   selectToBeginningOfNextWord: ->
     @modifySelection => @cursor.moveToBeginningOfNextWord()
 
-  # Selects text to the previous word boundary.
+  # Public: Selects text to the previous word boundary.
   selectToPreviousWordBoundary: ->
     @modifySelection => @cursor.moveToPreviousWordBoundary()
 
-  # Selects text to the next word boundary.
+  # Public: Selects text to the next word boundary.
   selectToNextWordBoundary: ->
     @modifySelection => @cursor.moveToNextWordBoundary()
 
-  # Moves the selection down one row.
+  # Public: Moves the selection down one row.
   addSelectionBelow: ->
     range = (@getGoalBufferRange() ? @getBufferRange()).copy()
     nextRow = range.end.row + 1
@@ -243,10 +258,13 @@ class Selection
       @editSession.addSelectionForBufferRange(range, goalBufferRange: range)
       break
 
+  # Public:
+  #
+  # FIXME: I have no idea what this does.
   getGoalBufferRange: ->
     @marker.getAttributes().goalBufferRange
 
-  # Moves the selection up one row.
+  # Public: Moves the selection up one row.
   addSelectionAbove: ->
     range = (@getGoalBufferRange() ? @getBufferRange()).copy()
     previousRow = range.end.row - 1
@@ -264,15 +282,20 @@ class Selection
       @editSession.addSelectionForBufferRange(range, goalBufferRange: range)
       break
 
-  # Replaces text at the current selection.
+  # Public: Replaces text at the current selection.
   #
-  # text - A {String} representing the text to add
-  # options - A hash containing the following options:
-  #           select: if `true`, selects the newly added text
-  #           autoIndent: if `true`, indents all inserted text appropriately
-  #           autoIndentNewline: if `true`, indent newline appropriately
-  #           autoDecreaseIndent: if `true`, decreases indent level appropriately (for example, when a closing bracket is inserted)
-
+  # * text:
+  #   A {String} representing the text to add
+  # * options
+  #    + select:
+  #      if `true`, selects the newly added text
+  #    + autoIndent:
+  #      if `true`, indents all inserted text appropriately
+  #    + autoIndentNewline:
+  #      if `true`, indent newline appropriately
+  #    + autoDecreaseIndent:
+  #      if `true`, decreases indent level appropriately (for example, when a
+  #      closing bracket is inserted)
   insertText: (text, options={}) ->
     oldBufferRange = @getBufferRange()
     @editSession.destroyFoldsContainingBufferRow(oldBufferRange.end.row)
@@ -298,6 +321,12 @@ class Selection
 
     newBufferRange
 
+  # Public: Indents the given text to the suggested level based on the grammar.
+  #
+  # * text:
+  #   The string to indent within the selection.
+  # * indentBasis:
+  #   The beginning indent level.
   normalizeIndents: (text, indentBasis) ->
     textPrecedingCursor = @cursor.getCurrentBufferLine()[0...@cursor.getBufferColumn()]
     isCursorInsideExistingLine = /\S/.test(textPrecedingCursor)
@@ -323,10 +352,12 @@ class Selection
 
     normalizedLines.join('\n')
 
-  # Indents the selection.
+  # Public: Indents the selection.
   #
-  # options - A hash with one key, `autoIndent`. If `true`, the indentation is
-  #           performed appropriately. Otherwise, {EditSession.getTabText} is used
+  # * options - A hash with one key,
+  #    + autoIndent:
+  #      If `true`, the indentation is performed appropriately. Otherwise,
+  #      {EditSession.getTabText} is used
   indent: ({ autoIndent }={})->
     { row, column } = @cursor.getBufferPosition()
 
@@ -342,28 +373,32 @@ class Selection
     else
       @indentSelectedRows()
 
-  # If the selection spans multiple rows, indents all of them.
+  # Public: If the selection spans multiple rows, indent all of them.
   indentSelectedRows: ->
     [start, end] = @getBufferRowRange()
     for row in [start..end]
       @editSession.buffer.insert([row, 0], @editSession.getTabText()) unless @editSession.buffer.lineLengthForRow(row) == 0
 
+  # Public: ?
   setIndentationForLine: (line, indentLevel) ->
     desiredIndentLevel = Math.max(0, indentLevel)
     desiredIndentString = @editSession.buildIndentString(desiredIndentLevel)
     line.replace(/^[\t ]*/, desiredIndentString)
 
-  # Performs a backspace, removing the character found behind the selection.
+  # Public: Removes the first character before the selection if the selection
+  # is empty otherwise it deletes the selection.
   backspace: ->
     @selectLeft() if @isEmpty() and not @editSession.isFoldedAtScreenRow(@cursor.getScreenRow())
     @deleteSelectedText()
 
-  # Performs a backspace to the beginning of the current word, removing characters found there.
+  # Public: Removes from the start of the selection to the beginning of the
+  # current word if the selection is empty otherwise it deletes the selection.
   backspaceToBeginningOfWord: ->
     @selectToBeginningOfWord() if @isEmpty()
     @deleteSelectedText()
 
-  # Performs a backspace to the beginning of the current line, removing characters found there.
+  # Public: Removes from the beginning of the line which the selection begins on
+  # all the way through to the end of the selection.
   backspaceToBeginningOfLine: ->
     if @isEmpty() and @cursor.isAtBeginningOfLine()
       @selectLeft()
@@ -371,7 +406,8 @@ class Selection
       @selectToBeginningOfLine()
     @deleteSelectedText()
 
-  # Performs a delete, removing the character found ahead of the cursor position.
+  # Public: Removes the selection or the next character after the start of the
+  # selection if the selection is empty.
   delete: ->
     if @isEmpty()
       if @cursor.isAtEndOfLine() and fold = @editSession.largestFoldStartingAtScreenRow(@cursor.getScreenRow() + 1)
@@ -380,12 +416,13 @@ class Selection
         @selectRight()
     @deleteSelectedText()
 
-  # Performs a delete to the end of the current word, removing characters found there.
+  # Public: Removes the selection or all characters from the start of the
+  # selection to the end of the current word if nothing is selected.
   deleteToEndOfWord: ->
     @selectToEndOfWord() if @isEmpty()
     @deleteSelectedText()
 
-  # Deletes the selected text.
+  # Public: Removes only the selected text.
   deleteSelectedText: ->
     bufferRange = @getBufferRange()
     if bufferRange.isEmpty() and fold = @editSession.largestFoldContainingBufferRow(bufferRange.start.row)
@@ -393,7 +430,9 @@ class Selection
     @editSession.buffer.delete(bufferRange) unless bufferRange.isEmpty()
     @cursor?.setBufferPosition(bufferRange.start)
 
-  # Deletes the line.
+  # Public: Removes the line at the beginning of the selection if the selection
+  # is empty unless the selection spans multiple lines in which case all lines
+  # are removed.
   deleteLine: ->
     if @isEmpty()
       start = @cursor.getScreenRow()
@@ -410,7 +449,7 @@ class Selection
         end--
       @editSession.buffer.deleteRows(start, end)
 
-  # Joins the current line with the one below it.
+  # Public: Joins the current line with the one below it.
   #
   # If there selection spans more than one line, all the lines are joined together.
   joinLine: ->
@@ -438,6 +477,7 @@ class Selection
       @setBufferRange(newSelectedRange)
       joinMarker.destroy()
 
+  # Public: Removes one level of indent from the currently selected rows.
   outdentSelectedRows: ->
     [start, end] = @getBufferRowRange()
     buffer = @editSession.buffer
@@ -446,33 +486,41 @@ class Selection
       if matchLength = buffer.lineForRow(row).match(leadingTabRegex)?[0].length
         buffer.delete [[row, 0], [row, matchLength]]
 
+  # Public: Sets the indentation level of all selected rows to values suggested
+  # by the relevant grammars.
   autoIndentSelectedRows: ->
     [start, end] = @getBufferRowRange()
     @editSession.autoIndentBufferRows(start, end)
 
-  # Wraps the selected lines in comments.
+  # Public: Wraps the selected lines in comments if they aren't currently part
+  # of a comment.
   #
-  # Returns an {Array} of the commented {Ranges}.
+  # Removes the comment if they are currently wrapped in a comment.
+  #
+  # Returns an Array of the commented {Range}s.
   toggleLineComments: ->
     @editSession.toggleLineCommentsForBufferRows(@getBufferRowRange()...)
 
-  # Performs a cut operation on the selection, until the end of the line.
+  # Public: Cuts the selection until the end of the line.
   #
-  # maintainPasteboard - A {Boolean} indicating TODO
+  # * maintainPasteboard:
+  #   ?
   cutToEndOfLine: (maintainPasteboard) ->
     @selectToEndOfLine() if @isEmpty()
     @cut(maintainPasteboard)
 
-  # Performs a cut operation on the selection.
+  # Public: Copies the selection to the pasteboard and then deletes it.
   #
-  # maintainPasteboard - A {Boolean} indicating TODO
+  # * maintainPasteboard:
+  #   ?
   cut: (maintainPasteboard=false) ->
     @copy(maintainPasteboard)
     @delete()
 
-  # Performs a copy operation on the selection.
+  # Public: Copies the current selection to the pasteboard.
   #
-  # maintainPasteboard - A {Boolean} indicating TODO
+  # * maintainPasteboard:
+  #   ?
   copy: (maintainPasteboard=false) ->
     return if @isEmpty()
     text = @editSession.buffer.getTextInRange(@getBufferRange())
@@ -484,19 +532,20 @@ class Selection
 
     pasteboard.write(text, metadata)
 
-  # Folds the selection.
+  # Public: Creates a fold containing the current selection.
   fold: ->
     range = @getBufferRange()
     @editSession.createFold(range.start.row, range.end.row)
     @cursor.setBufferPosition([range.end.row + 1, 0])
 
+  # Public: ?
   modifySelection: (fn) ->
     @retainSelection = true
     @plantTail()
     fn()
     @retainSelection = false
 
-  # Sets the marker's tail to the same position as the marker's head.
+  # Private: Sets the marker's tail to the same position as the marker's head.
   #
   # This only works if there isn't already a tail position.
   #
@@ -504,26 +553,31 @@ class Selection
   plantTail: ->
     @marker.plantTail()
 
-  # Identifies if a selection intersects with a given buffer range.
+  # Public: Identifies if a selection intersects with a given buffer range.
   #
-  # bufferRange - A {Range} to check against
+  # * bufferRange:
+  #   A {Range} to check against
   #
-  # Returns a {Boolean}.
+  # Returns a Boolean.
   intersectsBufferRange: (bufferRange) ->
     @getBufferRange().intersectsWith(bufferRange)
 
-  # Identifies if a selection intersects with another selection.
+  # Public: Identifies if a selection intersects with another selection.
   #
-  # otherSelection - A `Selection` to check against
+  # * otherSelection:
+  #   A {Selection} to check against
   #
-  # Returns a {Boolean}.
+  # Returns a Boolean.
   intersectsWith: (otherSelection) ->
     @getBufferRange().intersectsWith(otherSelection.getBufferRange())
 
-  # Merges two selections together.
+  # Public: Combines the given selection into this selection and then destroys
+  # the given selection.
   #
-  # otherSelection - A `Selection` to merge with
-  # options - A hash of options matching those found in {.setBufferRange}
+  # * otherSelection:
+  #   A {Selection} to merge with
+  # * options
+  #    + A hash of options matching those found in {.setBufferRange}
   merge: (otherSelection, options) ->
     myGoalBufferRange = @getGoalBufferRange()
     otherGoalBufferRange = otherSelection.getGoalBufferRange()
@@ -534,17 +588,19 @@ class Selection
     @setBufferRange(@getBufferRange().union(otherSelection.getBufferRange()), options)
     otherSelection.destroy()
 
+  # Public: ?
   compare: (other) ->
     @getBufferRange().compare(other.getBufferRange())
 
+  # Public: Returns true if it was locally created.
   isLocal: ->
     @marker.isLocal()
 
+  # Public: Returns true if it was created remotely.
   isRemote: ->
     @marker.isRemote()
 
-  ### Internal ###
-
+  # Private:
   screenRangeChanged: ->
     screenRange = @getScreenRange()
     @trigger 'screen-range-changed', screenRange