       @insertNewline()
       @moveCursorUp() if onFirstLine
 
-  # Indents the current line.
-  #
-  # options - A set of options equivalent to {Selection.indent}.
+  # Public: Indents the current line.
+  #
+  # * options
+  #    + A set of options equivalent to {Selection.indent}.
   indent: (options={})->
     options.autoIndent ?= @shouldAutoIndent()
     @mutateSelectedText (selection) -> selection.indent(options)
 
-  # Performs a backspace, removing the character found behind the cursor position.
+  # Public: Removes the character found behind the current cursor position.
+  #
+  # FIXME: Does this remove content from all cursors or the last one?
   backspace: ->
     @mutateSelectedText (selection) -> selection.backspace()
 
-  # Performs a backspace to the beginning of the current word, removing characters found there.
+  # Public: Removes all characters from the current cursor position until the
+  # beginging of the current word.
   backspaceToBeginningOfWord: ->
     @mutateSelectedText (selection) -> selection.backspaceToBeginningOfWord()
 
-  # Performs a backspace to the beginning of the current line, removing characters found there.
+  # Public: Removes all characters from the current cursor position to the start
+  # of the line.
   backspaceToBeginningOfLine: ->
     @mutateSelectedText (selection) -> selection.backspaceToBeginningOfLine()
 
-  # Performs a delete, removing the character found ahead of the cursor position.
+  # Public: Removes the current selection or the next character after the
+  # cursor.
   delete: ->
     @mutateSelectedText (selection) -> selection.delete()
 
-  # Performs a delete to the end of the current word, removing characters found there.
+  # Public: Removes all characters from the cursor until the end of the current
+  # word.
   deleteToEndOfWord: ->
     @mutateSelectedText (selection) -> selection.deleteToEndOfWord()
 
-  # Deletes the entire line.
+  # Public: Deletes the entire line.
   deleteLine: ->
     @mutateSelectedText (selection) -> selection.deleteLine()
 
-  # Indents the selected rows.
+  # Public: Indents the currently selected rows.
+  #
+  # FIXME: what does this do if no selection?
   indentSelectedRows: ->
     @mutateSelectedText (selection) -> selection.indentSelectedRows()
 
-  # Outdents the selected rows.
+  # Public: Outdents the selected rows.
+  #
+  # FIXME: what does this do if no selection?
   outdentSelectedRows: ->
     @mutateSelectedText (selection) -> selection.outdentSelectedRows()
 
-  # Wraps the lines within a selection in comments.
+  # Public: Wraps the lines within a selection in comments.
   #
   # If the language doesn't have comments, nothing happens.
-  #
-  # selection - The {Selection} to comment
   #
   # Returns an {Array} of the commented {Ranges}.
   toggleLineCommentsInSelection: ->
     @mutateSelectedText (selection) -> selection.toggleLineComments()
 
+  # Public: Indents selected lines based on grammar's suggested indent levels.
   autoIndentSelectedRows: ->
     @mutateSelectedText (selection) -> selection.autoIndentSelectedRows()
 
-  # Given a buffer range, this converts all `\t` characters to the appropriate {.getTabText} value.
-  #
-  # bufferRange - The {Range} to perform the replace in
+  # Public: Converts all indents to the current {.tabTabText} given a {Range}.
   normalizeTabsInBufferRange: (bufferRange) ->
     return unless @getSoftTabs()
     @scanInBufferRange /\t/, bufferRange, ({replace}) => replace(@getTabText())
 
-  # Performs a cut to the end of the current line.
-  #
-  # Characters are removed, but the text remains in the clipboard.
+  # Public: Copies and removes all characters from cursor to the end of the
+  # line.
   cutToEndOfLine: ->
     maintainPasteboard = false
     @mutateSelectedText (selection) ->
       selection.cutToEndOfLine(maintainPasteboard)
       maintainPasteboard = true
 
-  # Cuts the selected text.
+  # Public: Cuts the selected text.
   cutSelectedText: ->
     maintainPasteboard = false
     @mutateSelectedText (selection) ->
       selection.cut(maintainPasteboard)
       maintainPasteboard = true
 
-  # Copies the selected text.
+  # Public: Copies the selected text.
   copySelectedText: ->
     maintainPasteboard = false
     for selection in @getSelections()
       selection.copy(maintainPasteboard)
       maintainPasteboard = true
 
-  # Pastes the text in the clipboard.
-  #
-  # options - A set of options equivalent to {Selection.insertText}.
+  # Public: Pastes the text in the clipboard.
+  #
+  # * options:
+  #    + A set of options equivalent to {Selection.insertText}.
   pasteText: (options={}) ->
     [text, metadata] = pasteboard.read()
 

    @trigger 'destroyed'
    @off()

  serialize: -> @state.clone()
  getState: -> @state

  # Creates an {EditSession} with the same initial state
  copy: ->
    tabLength = @getTabLength()
    displayBuffer = @displayBuffer.copy()

      @setSelectedBufferRange(range)
      range

  # Public:
  #
  # FIXME: Not sure how to describe what this does.
  mergeCursors: ->
    positions = []
    for cursor in @getCursors()
