From 7ca8e31087f42bbefd9a765269b5aa588394f0c9 Mon Sep 17 00:00:00 2001
From: Nathan Sobo <nathan@github.com>
Date: Tue, 30 Apr 2013 05:12:13 -0600
Subject: [PATCH] Document Fold methods

---
 src/app/fold.coffee | 21 ++++++++++++++-------
 1 file changed, 14 insertions(+), 7 deletions(-)

diff --git a/src/app/fold.coffee b/src/app/fold.coffee
index d37d1811f..8661dcd54 100644
--- a/src/app/fold.coffee
+++ b/src/app/fold.coffee
@@ -1,15 +1,16 @@
 Range = require 'range'
 Point = require 'point'
 
-# Public: Represents a fold that's hiding text from the screen.
+# Public: Represents a fold that collapses multiple buffer lines into a single
+# line on the screen.
 #
-# Folds are the primary reason that screen ranges and buffer ranges vary. Their
-# creation is managed by the {DisplayBuffer}.
+# Their creation is managed by the {DisplayBuffer}.
 module.exports =
 class Fold
   displayBuffer: null
   marker: null
 
+  # Internal
   constructor: (@displayBuffer, @marker) ->
     @displayBuffer.foldsByMarkerId[@marker.id] = this
     @updateDisplayBuffer()
@@ -19,25 +20,27 @@ class Fold
       @updateDisplayBuffer() unless newRange.isEqual(oldRange)
     @marker.on 'destroyed', => @destroyed()
 
-  updateDisplayBuffer: ->
-    unless @isInsideLargerFold()
-      @displayBuffer.updateScreenLines(@getStartRow(), @getEndRow(), 0, updateMarkers: true)
-
+  # Returns whether this fold is contained within another fold
   isInsideLargerFold: ->
     @displayBuffer.findMarker(class: 'fold', containsBufferRange: @getBufferRange())?
 
+  # Destroys this fold
   destroy: ->
     @marker.destroy()
 
+  # Returns the fold's {Range} in buffer coordinates
   getBufferRange: ->
     @marker.getBufferRange()
 
+  # Returns the fold's start row as a {Number}.
   getStartRow: ->
     @getBufferRange().start.row
 
+  # Returns the fold's end row as a {Number}.
   getEndRow: ->
     @getBufferRange().end.row
 
+  # Returns a {String} representation of the fold.
   inspect: ->
     "Fold(#{@getStartRow()}, #{@getEndRow()})"
 
@@ -49,6 +52,10 @@ class Fold
 
   ## Internal ##
 
+  updateDisplayBuffer: ->
+    unless @isInsideLargerFold()
+      @displayBuffer.updateScreenLines(@getStartRow(), @getEndRow(), 0, updateMarkers: true)
+
   destroyed: ->
     delete @displayBuffer.foldsByMarkerId[@marker.id]
     @updateDisplayBuffer()