From 662ddf9fd6562b9951dfccfa65835fc0635a4a2a Mon Sep 17 00:00:00 2001
From: Garen Torikian <gjtorikian@gmail.com>
Date: Wed, 1 May 2013 17:21:05 -0700
Subject: [PATCH] Update documentation to push threshold back past 80%

---
 src/app/display-buffer.coffee           |  5 ++++
 src/app/edit-session.coffee             | 18 +++++++-------
 src/app/selection-view.coffee           |  2 +-
 src/app/selection.coffee                |  7 +++++-
 src/app/text-buffer.coffee              | 31 +++++++++++++++++++++++--
 src/app/text-mate-scope-selector.coffee |  2 +-
 src/app/token.coffee                    |  4 ++++
 7 files changed, 56 insertions(+), 13 deletions(-)

diff --git a/src/app/display-buffer.coffee b/src/app/display-buffer.coffee
index 8c5178306..bc26e908d 100644
--- a/src/app/display-buffer.coffee
+++ b/src/app/display-buffer.coffee
@@ -306,12 +306,17 @@ class DisplayBuffer
   setTabLength: (tabLength) ->
     @tokenizedBuffer.setTabLength(tabLength)
 
+  # Retrieves the grammar for the buffer.
   getGrammar: ->
     @tokenizedBuffer.grammar
 
+  # Sets the grammar for the buffer.
+  #
+  # grammar - Sets the new grammar rules
   setGrammar: (grammar) ->
     @tokenizedBuffer.setGrammar(grammar)
 
+  # Reloads the current grammar.
   reloadGrammar: ->
     @tokenizedBuffer.reloadGrammar()
 
diff --git a/src/app/edit-session.coffee b/src/app/edit-session.coffee
index bcb11b9a7..31f224edf 100644
--- a/src/app/edit-session.coffee
+++ b/src/app/edit-session.coffee
@@ -775,7 +775,7 @@ class EditSession
   destroyMarker: (args...) ->
     @displayBuffer.destroyMarker(args...)
 
-  # {Delegates to: TextBuffer.destroyMarker}
+  # {Delegates to: Buffer.getMarkerCount}
   getMarkerCount: ->
     @buffer.getMarkerCount()
 
@@ -1276,6 +1276,12 @@ class EditSession
   expandLastSelectionOverWord: ->
     @getLastSelection().expandOverWord()
 
+  # Selects the buffer range of the given marker.
+  #
+  # id - A {Number} indicating the marker's id
+  #
+  # Returns a {Boolean} value that is `true` if the marker contains a buffer
+  # range.
   selectMarker: (id) ->
     if bufferRange = @getMarkerBufferRange(id)
       @setSelectedBufferRange(bufferRange)
@@ -1333,19 +1339,15 @@ class EditSession
       @setCursorBufferPosition(cursorPosition) if cursorPosition
       cursorPosition = null
 
-  # Retrieves the current {EditSession}'s grammar.
-  #
-  # Returns a {String} indicating the language's grammar rules.
+  # {Delegates to: DisplayBuffer.getGrammar}
   getGrammar: ->
     @displayBuffer.getGrammar()
 
-  # Sets the current {EditSession}'s grammar.
-  #
-  # grammar - A {String} indicating the language's grammar rules.
+  # {Delegates to: DisplayBuffer.setGrammar}
   setGrammar: (grammar) ->
     @displayBuffer.setGrammar(grammar)
 
-  # Reloads the current grammar.
+  # {Delegates to: DisplayBuffer.reloadGrammar}
   reloadGrammar: ->
     @displayBuffer.reloadGrammar()
 
diff --git a/src/app/selection-view.coffee b/src/app/selection-view.coffee
index 2adcf7627..bf9ccc777 100644
--- a/src/app/selection-view.coffee
+++ b/src/app/selection-view.coffee
@@ -2,10 +2,10 @@ Point = require 'point'
 Range = require 'range'
 {View, $$} = require 'space-pen'
 
+# Internal:
 module.exports =
 class SelectionView extends View
 
-  # Internal: Establishes the DOM for the selection view.
   @content: ->
     @div class: 'selection'
 
diff --git a/src/app/selection.coffee b/src/app/selection.coffee
index 04f38381a..6ce2c15f8 100644
--- a/src/app/selection.coffee
+++ b/src/app/selection.coffee
@@ -281,7 +281,7 @@ class Selection
   # Indents the selection.
   #
   # options - A hash with one key, `autoIndent`. If `true`, the indentation is
-  #           performed appropriately. Otherwise, {EditSession#getTabText} is used
+  #           performed appropriately. Otherwise, {EditSession.getTabText} is used
   indent: ({ autoIndent }={})->
     { row, column } = @cursor.getBufferPosition()
 
@@ -499,6 +499,11 @@ class Selection
     fn()
     @retainSelection = false
 
+  # Sets the marker's tail to the same position as the marker's head.
+  #
+  # This only works if there isn't already a tail position.
+  #
+  # Returns a {Point} representing the new tail position.
   placeTail: ->
     @editSession.placeMarkerTail(@marker)
 
diff --git a/src/app/text-buffer.coffee b/src/app/text-buffer.coffee
index 9e030c63f..93a9a2e6f 100644
--- a/src/app/text-buffer.coffee
+++ b/src/app/text-buffer.coffee
@@ -207,6 +207,11 @@ class Buffer
   lineForRow: (row) ->
     @lines[row]
 
+  # Given a row, returns its line ending.
+  #
+  # row - A {Number} indicating the row.
+  #
+  # Returns a {String}, or `undefined` if `row` is the final row.
   lineEndingForRow: (row) ->
     @lineEndings[row] unless row is @getLastRow()
 
@@ -221,6 +226,11 @@ class Buffer
   lineLengthForRow: (row) ->
     @lines[row].length
 
+  # Given a row, returns the length of the line ending
+  #
+  # row - A {Number} indicating the row.
+  #
+  # Returns a {Number}.
   lineEndingLengthForRow: (row) ->
     (@lineEndingForRow(row) ? '').length
 
@@ -366,8 +376,6 @@ class Buffer
   #
   # editSession - The {EditSession} associated with the buffer.
   redo: (editSession) -> @undoManager.redo(editSession)
-  commit: -> @undoManager.commit()
-  abort: -> @undoManager.abort()
 
   # Saves the buffer.
   save: ->
@@ -405,6 +413,9 @@ class Buffer
   # Returns a {Boolean}.
   isEmpty: -> @lines.length is 1 and @lines[0].length is 0
 
+  # Retrieves all the valid markers in the buffer.
+  #
+  # Returns an {Array} of {BufferMarker}s.
   getMarkers: ->
     _.values(@validMarkers)
 
@@ -445,9 +456,21 @@ class Buffer
     delete @validMarkers[id]
     delete @invalidMarkers[id]
 
+  # Retrieves the positions of every marker's head.
+  #
+  # Returns an {Array} of {Point}s.
   getMarkerPosition: (args...) ->
     @getMarkerHeadPosition(args...)
 
+  # Sets the positions of every marker's head.
+  #
+  # id - A {Number} representing the marker to change
+  # position - The new {Point} to place the head
+  # options - A hash with the following keys:
+  #         clip: if `true`, the point is [clipped]{Buffer.clipPosition}
+  #         bufferChanged: if `true`, indicates that the {Buffer} should trigger an event that it's changed
+  #
+  # Returns a {Point} representing the new head position.
   setMarkerPosition: (args...) ->
     @setMarkerHeadPosition(args...)
 
@@ -708,6 +731,10 @@ class Buffer
 
   ### Internal ###
 
+  commit: -> @undoManager.commit()
+
+  abort: -> @undoManager.abort()
+
   change: (oldRange, newText, options) ->
     oldRange = Range.fromObject(oldRange)
     operation = new BufferChangeOperation({buffer: this, oldRange, newText, options})
diff --git a/src/app/text-mate-scope-selector.coffee b/src/app/text-mate-scope-selector.coffee
index 46408c066..d5713356b 100644
--- a/src/app/text-mate-scope-selector.coffee
+++ b/src/app/text-mate-scope-selector.coffee
@@ -1,7 +1,7 @@
 PEG = require 'pegjs'
 fsUtils = require 'fs-utils'
 
-# Public: Test a stack of scopes to see if they match a scope selector.
+# Internal: Test a stack of scopes to see if they match a scope selector.
 module.exports =
 class TextMateScopeSelector
   @parser: null
diff --git a/src/app/token.coffee b/src/app/token.coffee
index 01707dd2d..5b2725612 100644
--- a/src/app/token.coffee
+++ b/src/app/token.coffee
@@ -7,10 +7,14 @@ class Token
   isAtomic: null
   isHardTab: null
 
+  ### Internal ###
+
   constructor: ({@value, @scopes, @isAtomic, @bufferDelta, @isHardTab}) ->
     @screenDelta = @value.length
     @bufferDelta ?= @screenDelta
 
+  ### Public ###
+
   isEqual: (other) ->
     @value == other.value and _.isEqual(@scopes, other.scopes) and !!@isAtomic == !!other.isAtomic