       else
         new Point(row, column)
 
+  # Public: Returns a {Point} at [0, 0]
   getFirstPosition: ->
     new Point(0, 0)
 
+  # Public: Returns a {Point} representing the maximal position in the buffer.
   getLastPosition: ->
     lastRow = @getLastRow()
     new Point(lastRow, @lineLengthForRow(lastRow))
 
+  # Public: Given a {Point} representing a position in the buffer, returns a
+  # {Number} representing the absolute character offset of that location in the
+  # buffer, inclusive of newlines. The position is clipped prior to translating.
   characterIndexForPosition: (position) ->
     {row, column} = @clipPosition(Point.fromObject(position))
 

    @markers?.handleBufferChange(patch)
    patch

  applyPatch: ({oldRange, newRange, oldText, newText, markerPatches}) ->
    startRow = oldRange.start.row
    endRow = oldRange.end.row

    else
      new Range(start, end)

  # Public: Clips the given point so it is at a valid position in the buffer.
  # For example, the position (1, 100) is out of bounds if the line at row 1 is
  # only 10 characters long, and it would be clipped to (1, 10)
  clipPosition: (position) ->
    position = Point.fromObject(position)
    {row, column} = position
