# HG changeset patch
# User Matt Harbison <matt_harbison@yahoo.com>
# Date 1558666211 14400
# Node ID c3484ddbdb9621256d597ed86b90d229c59c2af9
# Parent  0546ead39a7ee2b89f3bcf2567d4e3778a4c50c3
manifest: add some documentation to _lazymanifest python code

It was not particularly easy figuring out the design of this class and keeping
track of how the pieces work.  So might as well write some of it down for the
next person.

diff -r 0546ead39a7e -r c3484ddbdb96 mercurial/manifest.py
--- a/mercurial/manifest.py	Thu May 23 21:54:24 2019 -0400
+++ b/mercurial/manifest.py	Thu May 23 22:50:11 2019 -0400
@@ -126,6 +126,22 @@
     return (a > b) - (a < b)
 
 class _lazymanifest(object):
+    """A pure python manifest backed by a byte string.  It is supplimented with
+    internal lists as it is modified, until it is compacted back to a pure byte
+    string.
+
+    ``data`` is the initial manifest data.
+
+    ``positions`` is a list of offsets, one per manifest entry.  Positive
+    values are offsets into ``data``, negative values are offsets into the
+    ``extradata`` list.  When an entry is removed, its entry is dropped from
+    ``positions``.  The values are encoded such that when walking the list and
+    indexing into ``data`` or ``extradata`` as appropriate, the entries are
+    sorted by filename.
+
+    ``extradata`` is a list of (key, hash, flags) for entries that were added or
+    modified since the manifest was created or compacted.
+    """
     def __init__(self, data, positions=None, extrainfo=None, extradata=None,
                  hasremovals=False):
         if positions is None:
@@ -246,6 +262,8 @@
         self.positions = self.positions[:needle] + self.positions[needle + 1:]
         self.extrainfo = self.extrainfo[:needle] + self.extrainfo[needle + 1:]
         if cur >= 0:
+            # This does NOT unsort the list as far as the search functions are
+            # concerned, as they only examine lines mapped by self.positions.
             self.data = self.data[:cur] + '\x00' + self.data[cur + 1:]
             self.hasremovals = True
 
@@ -297,6 +315,10 @@
             if self.positions[i] >= 0:
                 cur = self.positions[i]
                 last_cut = cur
+
+                # Collect all contiguous entries in the buffer at the current
+                # offset, breaking out only for added/modified items held in
+                # extradata, or a deleted line prior to the next position.
                 while True:
                     self.positions[i] = offset
                     i += 1