Document new methods

src/app/buffer-marker.coffee

@@ -162,12 +162,19 @@ class BufferMarker
   unobserve: (callback) ->
     @off 'changed', callback
 
+  # Destroys the marker
   destroy: ->
     @buffer.destroyMarker(@id)
 
+  # Returns a {Boolean} indicating whether the marker is valid. Markers can be
+  # invalidated when a region surrounding them in the buffer is changed.
   isValid: ->
     @buffer.getMarker(@id)?
 
+  # Returns a {Boolean} indicating whether the marker has been destroyed. A marker
+  # can be invalid without being destroyed, in which case undoing the invalidating
+  # operation would restore the marker. Once a marker is destroyed by calling
+  # {Marker.destroy}, no undo/redo operation can ever bring it back.
   isDestroyed: ->
     not (@buffer.validMarkers[@id]? or @buffer.invalidMarkers[@id]?)
 

src/app/display-buffer-marker.coffee

@@ -131,12 +131,19 @@ class DisplayBufferMarker
   isReversed: ->
     @bufferMarker.isReversed()
 
+  # Returns a {Boolean} indicating whether the marker is valid. Markers can be
+  # invalidated when a region surrounding them in the buffer is changed.
   isValid: ->
     @bufferMarker.isValid()
 
+  # Returns a {Boolean} indicating whether the marker has been destroyed. A marker
+  # can be invalid without being destroyed, in which case undoing the invalidating
+  # operation would restore the marker. Once a marker is destroyed by calling
+  # {Marker.destroy}, no undo/redo operation can ever bring it back.
   isDestroyed: ->
     @bufferMarker.isDestroyed()
 
+  # Destroys the marker
   destroy: ->
     delete @displayBuffer.markers[@id]
     @bufferMarker.destroy()

src/app/display-buffer.coffee

@@ -522,9 +522,22 @@ class DisplayBuffer
     @buffer.destroyMarker(id)
     delete @markers[id]
 
+  # Finds the first marker satisfying the given attributes
+  #
+  # Refer to {DisplayBuffer.findMarkers} for details.
+  #
+  # Returns a {DisplayBufferMarker} or null
   findMarker: (attributes) ->
     @findMarkers(attributes)[0]
 
+  # Finds all valid markers satisfying the given attributes
+  #
+  # attributes - The attributes against which to compare the markers' attributes
+  #   There are some reserved keys that match against derived marker properties:
+  #   startBufferRow - The buffer row at which the marker starts
+  #   endBufferRow - The buffer row at which the marker ends
+  #
+  # Returns an {Array} of {DisplayBufferMarker}s
   findMarkers: (attributes) ->
     { startBufferRow, endBufferRow } = attributes
     attributes.startRow = startBufferRow if startBufferRow?

src/app/edit-session.coffee

@@ -922,6 +922,7 @@ class EditSession
   # Public #
   ###
 
+  # Returns a valid {DisplayBufferMarker} object for the given id if one exists.
   getMarker: (id) ->
     @displayBuffer.getMarker(id)
 
@@ -1410,6 +1411,9 @@ class EditSession
   expandLastSelectionOverWord: ->
     @getLastSelection().expandOverWord()
 
+  # Selects the range associated with the given marker if it is valid.
+  #
+  # Returns the selected {Range} or a falsy value if the marker is invalid.
   selectMarker: (marker) ->
     if marker.isValid()
       range = marker.getBufferRange()