revlog: improve documentation

revlog: improve documentation

There are a lot of functions and variables doing similar things.
Document the role and functionality of each to make it easier to
grok.

--- a/mercurial/revlog.py	Sat Nov 21 22:28:01 2015 -0800
+++ b/mercurial/revlog.py	Sun Nov 22 16:23:20 2015 -0800
@@ -205,14 +205,21 @@
         self.indexfile = indexfile
         self.datafile = indexfile[:-2] + ".d"
         self.opener = opener
+        # 3-tuple of (node, rev, text) for a raw revision.
         self._cache = None
+        # 2-tuple of (rev, baserev) defining the base revision the delta chain
+        # begins at for a revision.
         self._basecache = None
+        # 2-tuple of (offset, data) of raw data from the revlog at an offset.
         self._chunkcache = (0, '')
+        # How much data to read and cache into the raw revlog data cache.
         self._chunkcachesize = 65536
         self._maxchainlen = None
         self._aggressivemergedeltas = False
         self.index = []
+        # Mapping of partial identifiers to full nodes.
         self._pcache = {}
+        # Mapping of revision integer to full node.
         self._nodecache = {nullid: nullrev}
         self._nodepos = None
 
@@ -926,6 +933,10 @@
         return hash(text, p1, p2) != node
 
     def _addchunk(self, offset, data):
+        """Add a segment to the revlog cache.
+
+        Accepts an absolute offset and the data that is at that location.
+        """
         o, d = self._chunkcache
         # try to add to existing cache
         if o + len(d) == offset and len(d) + len(data) < _chunksize:
@@ -934,13 +945,15 @@
             self._chunkcache = offset, data
 
     def _loadchunk(self, offset, length, df=None):
-        """Load a chunk/segment from the revlog.
+        """Load a segment of raw data from the revlog.
 
-        Accepts absolute offset, length to read, and an optional existing
+        Accepts an absolute offset, length to read, and an optional existing
         file handle to read from.
 
         If an existing file handle is passed, it will be seeked and the
         original seek position will NOT be restored.
+
+        Returns a str or buffer of raw byte data.
         """
         if df is not None:
             closehandle = False
@@ -968,6 +981,16 @@
         return d
 
     def _getchunk(self, offset, length, df=None):
+        """Obtain a segment of raw data from the revlog.
+
+        Accepts an absolute offset, length of bytes to obtain, and an
+        optional file handle to the already-opened revlog. If the file
+        handle is used, it's original seek position will not be preserved.
+
+        Requests for data may be returned from a cache.
+
+        Returns a str or a buffer instance of raw byte data.
+        """
         o, d = self._chunkcache
         l = len(d)
 
@@ -982,6 +1005,18 @@
         return self._loadchunk(offset, length, df=df)
 
     def _chunkraw(self, startrev, endrev, df=None):
+        """Obtain a segment of raw data corresponding to a range of revisions.
+
+        Accepts the start and end revisions and an optional already-open
+        file handle to be used for reading. If the file handle is read, its
+        seek position will not be preserved.
+
+        Requests for data may be satisfied by a cache.
+
+        Returns a str or a buffer instance of raw byte data. Callers will
+        need to call ``self.start(rev)`` and ``self.length()`` to determine
+        where each revision's data begins and ends.
+        """
         start = self.start(startrev)
         end = self.end(endrev)
         if self._inline:
@@ -991,12 +1026,29 @@
         return self._getchunk(start, length, df=df)
 
     def _chunk(self, rev, df=None):
+        """Obtain a single decompressed chunk for a revision.
+
+        Accepts an integer revision and an optional already-open file handle
+        to be used for reading. If used, the seek position of the file will not
+        be preserved.
+
+        Returns a str holding uncompressed data for the requested revision.
+        """
         return decompress(self._chunkraw(rev, rev, df=df))
 
     def _chunks(self, revs, df=None):
-        '''faster version of [self._chunk(rev) for rev in revs]
+        """Obtain decompressed chunks for the specified revisions.
 
-        Assumes that revs is in ascending order.'''
+        Accepts an iterable of numeric revisions that are assumed to be in
+        ascending order. Also accepts an optional already-open file handle
+        to be used for reading. If used, the seek position of the file will
+        not be preserved.
+
+        This function is similar to calling ``self._chunk()`` multiple times,
+        but is faster.
+
+        Returns a list with decompressed data for each requested revision.
+        """
         if not revs:
             return []
         start = self.start
@@ -1032,6 +1084,7 @@
         return l
 
     def _chunkclear(self):
+        """Clear the raw chunk cache."""
         self._chunkcache = (0, '')
 
     def deltaparent(self, rev):