Document RowMap

src/app/row-map.coffee

@@ -1,3 +1,26 @@
+## Internal ##
+
+# Facilitates the mapping of screen rows to buffer rows and vice versa. All row
+# ranges dealt with by this class are end-row exclusive. For example, a fold of
+# rows 4 through 8 would be expressed as `mapBufferRowRange(4, 9, 1)`, which maps
+# the region from 4 to 9 in the buffer to a single screen row. Conversely, a
+# soft-wrapped screen line means there are multiple screen rows corresponding to
+# a single buffer row, as follows: `mapBufferRowRange(4, 5, 3)`. That says that
+# buffer row 4 maps to 3 rows on screen.
+#
+# The RowMap revolves around the `@regions` array. Each region describes a number
+# of rows in both the screen and buffer coordinate spaces. So if you inserted a
+# single fold from 5-10, the regions array would look like this:
+#
+# ```
+# [{bufferRows: 5, screenRows: 5}, {bufferRows: 5, screenRows: 1}]
+# ```
+#
+# The first region expresses an iso-mapping, a region in which one buffer row
+# is equivalent to one screen row. The second region expresses the fold, with
+# 5 buffer rows mapping to a single screen row. Position translation functions
+# by traversing through these regions and summing the number of rows traversed
+# in both the screen and the buffer.
 module.exports =
 class RowMap
   constructor: ->
@@ -11,6 +34,10 @@ class RowMap
       screenRow += targetBufferRow - bufferRow
       [screenRow, screenRow + 1]
 
+  # This will return just the given buffer row if it is part of an iso region,
+  # but if it is part of a fold it will return the range of the entire fold. This
+  # helps the DisplayBuffer always start processing at the beginning of a fold
+  # for changes that occur inside the fold.
   bufferRowRangeForBufferRow: (targetBufferRow) ->
     { region, screenRow, bufferRow } = @traverseToBufferRow(targetBufferRow)
     if region and region.bufferRows != region.screenRows # 1:n region
@@ -26,6 +53,11 @@ class RowMap
       bufferRow += targetScreenRow - screenRow
       [bufferRow, bufferRow + 1]
 
+  # This method is used to create new regions, storing a mapping between a range
+  # of buffer rows to a certain number of screen rows. It will never add or remove
+  # rows in either coordinate space, meaning that it never changes the position
+  # of subsequent regions. It will overwrite or split existing regions that overlap
+  # with the region being stored however.
   mapBufferRowRange: (startBufferRow, endBufferRow, screenRows) ->
     { index, bufferRow, screenRow } = @traverseToBufferRow(startBufferRow)
 
@@ -63,6 +95,8 @@ class RowMap
 
     @regions[overlapStartIndex..overlapEndIndex] = newRegions
 
+  # This method records insertion or removal of rows in the buffer, adjusting the
+  # buffer dimension of regions following the start row accordingly.
   applyBufferDelta: (startBufferRow, delta) ->
     return if delta is 0
     { index, bufferRow } = @traverseToBufferRow(startBufferRow)
@@ -84,6 +118,8 @@ class RowMap
         bufferRow += bufferRows
         index++
 
+  # This method records insertion or removal of rows on the screen, adjusting the
+  # screen dimension of regions following the start row accordingly.
   applyScreenDelta: (startScreenRow, delta) ->
     return if delta is 0
     { index, screenRow } = @traverseToScreenRow(startScreenRow)