 TextManipulation = module.exports =
   ElementList: ElementList
 
-  # Get inner range and non-nested subranges for nearest enclosing list that contains
-  # both range start and range end (which may be at different depth levels).
+  ###*
+   * Get inner range and non-nested subranges for nearest enclosing list that contains
+   * both range start and range end (which may be at different depth levels).
+   * @param  {string}     bufferText   - Buffer text that contains the element list
+   * @param  {number[][]} ignoreRanges - List of ranges that should be ignored while recoginizing list elements.
+   * @param  {number[]}   range        - Range ([startIx, endIx]) corresponding to current text selection.
+   * @return {{ listRange: number[], nonNestedRanges:number[][]}}
+  ###
   getListContainingRange: (bufferText, ignoreRanges, range) ->
     leftIx = rightIx = range[0]
+    # Starting at the range start, repeatedly take enclosing lists, until the range end is also included or we arrive at the document bounds
     loop
-      # Repeatedly take enclosing lists, until the range is included or we arrive at the document bounds
       list = @getEnclosingList bufferText, ignoreRanges, leftIx, rightIx
       break unless list? and list.listRange[0] > 0 and list.listRange[1] < range[1] # no need to check for end of file, because of range[1] check
       leftIx = list.listRange[0] - 1
       rightIx = list.listRange[1] + 1
     list
 
-  # Get inner range and non-nested subranges for nearest enclosing list that holds [start, end>
-  # PRECONDITION: [start, end> is either empty or a well-formed list
+  ###*
+   * Get inner range and non-nested subranges for nearest enclosing list that holds [start, end>.
+   * PRECONDITION: [start, end> is either empty or a well-formed list.
+   * @param  {string}     bufferText
+   * @param  {number[][]} ignoreRanges
+   * @param  {number}     start        - [description]
+   * @param  {number}     end          - [description]
+   * @return {{listRange: number[], nonNestedRanges:number[][]}}
+  ###
   getEnclosingList: (bufferText, ignoreRanges, start, end) ->
     rangesToOpen = @findMatchingOpeningBracket bufferText, ignoreRanges, start, false
     rangesToClose = @findMatchingClosingBracket bufferText, ignoreRanges, end, false

        sepTrailingWhitespace = @elts[1].leadingWhitespace
        {leadingWhitespace: sepLeadingWhitespace, sepChar: sepChar, trailingWhitespace: sepTrailingWhitespace}

ElementList.getElementList = (bufferText, ignoreRanges, ixRange) ->
    containingList = TextManipulation.getListContainingRange bufferText, ignoreRanges, ixRange
    if containingList?
      new ElementList(bufferText, containingList)
    else
      null


###*
 * Classes and methods for analyzing and manipulating list elements.
 *
 * @module TextManipulation
###

{Range} = require 'atom'
_ = require 'underscore-plus'

