 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

      atom.notifications.addFatalError 'List-edit: Unknown opening bracket \'' + openingBracket + '\''
      undefined

  getOpeningBracketFor: (closingBracket) ->
    ix = @closeBracketChars.indexOf(closingBracket)
    if ix >= 0

        return ignoreRanges[ix]
    null

  ###*
   * If ix is inside an ignored range, return an index to the character following that ignored range, otherwise return ix.
   * PRECONDITION: ranges do not connect (i.e. there is at least one character in between)
   * @param  {number[][]} ignoreRanges
   * @param  {number}     ix
   * @return {number}
  ###
  forwardSkipIgnored: (ignoreRanges, ix) ->
    (@findRangeForIndex ignoreRanges, ix)?[1] ? ix

  # NOTE: for backwardSkipIgnored, ix denotes a position after the character, so it skips
  #       if the preceding character is in a skip range: e.g. backwardSkipIgnored([[1,2]],2) == 1
  ###*
   * If the character preceding ix is inside an ignored range, return an index to the start of the ignored range, otherwise return ix.
   * e.g. backwardSkipIgnored([[1,3]],3) == 1
   * PRECONDITION: ranges do not connect (i.e. there is at least one character in between)
   * @param  {number[][]} ignoreRanges
   * @param  {number}     ix
   * @return {number}
  ###
  backwardSkipIgnored: (ignoreRanges, ix) ->
    (@findRangeForIndex ignoreRanges, ix-1)?[0] ? ix


  ###*
   * Convert list of ranges that cover the entire list except its sublists, to ranges for its elements.
   * The first separator encountered is expected to be the separator for the entire list.
   * NOTE: nonNestedRanges may start before startIx and end after endIx, but only element ranges in the
   *       range [startIx, endIx> will be returned.
   * @param  {string}     bufferText
   * @param  {number}     startIx         - Start index of list contents (== index of opening bracket + 1)
   * @param  {number}     endIx           - End index of list contents (== index of closing bracket, as ranges don't include end)
   * @param  {number[][]} nonNestedRanges - List of ranges for those parts of the list that are not nested sublists.
   * @return {number[][]} List-element index ranges
  ###
  getElementRangesFromNonNested: (bufferText, startIx, endIx, nonNestedRanges) ->
    # Because lists with empty elements are not uncommon, we return empty element ranges for empty or whitespace-only
    # ranges between separators. If the entire list is empty, however, we return no element ranges.
