[PATCH 3 of 3 STABLE] manifest: add some documentation to _lazymanifest python code

[Matt Harbison]

# HG changeset patch
# User Matt Harbison <matt_harbison at yahoo.com>
# Date 1558666211 14400
#      Thu May 23 22:50:11 2019 -0400
# Branch stable
# Node ID be145b004d53ec01e5a5ffcd4ca0f7e6245746b1
# Parent  4cb54e688c12790fcf3cacff2b2fb3822e9f8e8f
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 --git a/mercurial/manifest.py b/mercurial/manifest.py
--- a/mercurial/manifest.py
+++ b/mercurial/manifest.py
@@ -126,6 +126,22 @@ def _cmp(a, b):
     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 @@ class _lazymanifest(object):
         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 @@ class _lazymanifest(object):
             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