# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@octobus.net>
# Date 1565214901 -7200
# Node ID 616aa62e5027f4ffdab3a743094aae9c55a254d6
# Parent  bf070a59546a8fd50518f4e8fa5ea29e25fa66ba
revlog: add some documentation to `_revisiondata` code

diff -r bf070a59546a -r 616aa62e5027 mercurial/revlog.py
--- a/mercurial/revlog.py	Wed Aug 07 23:52:55 2019 +0200
+++ b/mercurial/revlog.py	Wed Aug 07 23:55:01 2019 +0200
@@ -1611,6 +1611,7 @@
         return self._revisiondata(nodeorrev, _df, raw=raw)
 
     def _revisiondata(self, nodeorrev, _df=None, raw=False):
+        # deal with <nodeorrev> argument type
         if isinstance(nodeorrev, int):
             rev = nodeorrev
             node = self.node(rev)
@@ -1618,19 +1619,31 @@
             node = nodeorrev
             rev = None
 
+        # fast path the special `nullid` rev
         if node == nullid:
             return ""
 
+        # revision in the cache (could be useful to apply delta)
         cachedrev = None
+        # the revlog's flag for this revision
+        # (usually alter its state or content)
         flags = None
+        # The text as stored inside the revlog. Might be the revision or might
+        # need to be processed to retrieve the revision.
         rawtext = None
+        # An intermediate text to apply deltas to
         basetext = None
+
+        # Check if we have the entry in cache
+        # The cache entry looks like (node, rev, rawtext)
         if self._revisioncache:
             if self._revisioncache[0] == node:
                 # _cache only stores rawtext
                 # rawtext is reusable. but we might need to run flag processors
                 rawtext = self._revisioncache[2]
                 if raw:
+                    # if we don't want to process the raw text and that raw
+                    # text is cached, we can exit early.
                     return rawtext
                 # duplicated, but good for perf
                 if rev is None: