# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@octobus.net>
# Date 1582816157 -3600
# Node ID 283fd803afa5ff138e06622e06d9f75dd06673d5
# Parent  02c47b74366c8ccb0d838e0f1e537aab28371eaa
nodemap: document the docket attributes

More documentation rarely hurts.

Differential Revision: https://phab.mercurial-scm.org/D8182

diff -r 02c47b74366c -r 283fd803afa5 mercurial/revlogutils/nodemap.py
--- a/mercurial/revlogutils/nodemap.py	Tue Mar 10 13:10:53 2020 -0400
+++ b/mercurial/revlogutils/nodemap.py	Thu Feb 27 16:09:17 2020 +0100
@@ -226,9 +226,20 @@
     def __init__(self, uid=None):
         if uid is None:
             uid = _make_uid()
+        # a unique identifier for the data file:
+        #   - When new data are appended, it is preserved.
+        #   - When a new data file is created, a new identifier is generated.
         self.uid = uid
+        # the tipmost revision stored in the data file. This revision and all
+        # revision before it are expected to be encoded in the data file.
         self.tip_rev = None
+        # the size (in bytes) of the persisted data to encode the nodemap valid
+        # for `tip_rev`.
+        #   - data file shorter than this are corrupted,
+        #   - any extra data should be ignored.
         self.data_length = None
+        # the amount (in bytes) of "dead" data, still in the data file but no
+        # longer used for the nodemap.
         self.data_unused = 0
 
     def copy(self):