From 6f34d0b346b01fbee151a92a4c6f5439e77c88ba Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Mon, 29 Apr 2013 10:58:29 -0600
Subject: [PATCH] Document new methods

---
 src/app/buffer-marker.coffee         |  7 +++++++
 src/app/display-buffer-marker.coffee |  7 +++++++
 src/app/display-buffer.coffee        | 13 +++++++++++++
 src/app/edit-session.coffee          |  4 ++++
 4 files changed, 31 insertions(+)

diff --git a/src/app/buffer-marker.coffee b/src/app/buffer-marker.coffee
index a5129703d..27f6598c3 100644
--- a/src/app/buffer-marker.coffee
+++ b/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]?)
 
diff --git a/src/app/display-buffer-marker.coffee b/src/app/display-buffer-marker.coffee
index dd78d1903..379e6f062 100644
--- a/src/app/display-buffer-marker.coffee
+++ b/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()
diff --git a/src/app/display-buffer.coffee b/src/app/display-buffer.coffee
index 8059cc563..595bfa481 100644
--- a/src/app/display-buffer.coffee
+++ b/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?
diff --git a/src/app/edit-session.coffee b/src/app/edit-session.coffee
index 752d68f0e..c7478f7e0 100644
--- a/src/app/edit-session.coffee
+++ b/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()