[PATCH] Improve some docstrings relating to changegroups and prepush()

[Greg Ward]

# HG changeset patch
# User Greg Ward <greg-hg at gerg.ca>
# Date 1252447139 14400
# Node ID cd5f18465cb8c424df0bb9a9078e8eeec2c9f8e2
# Parent  2bc86906e975f38d88c495b833d805254b961848
Improve some docstrings relating to changegroups and prepush().

diff --git a/mercurial/changegroup.py b/mercurial/changegroup.py
--- a/mercurial/changegroup.py
+++ b/mercurial/changegroup.py
@@ -10,7 +10,7 @@
 import struct, os, bz2, zlib, tempfile
 
 def getchunk(source):
-    """get a chunk from a changegroup"""
+    """return the next chunk from changegroup 'source' as a string"""
     d = source.read(4)
     if not d:
         return ""
@@ -25,7 +25,8 @@
     return d
 
 def chunkiter(source):
-    """iterate through the chunks in source"""
+    """iterate through the chunks in source, yielding a sequence of chunks
+    (strings)"""
     while 1:
         c = getchunk(source)
         if not c:
@@ -33,10 +34,11 @@
         yield c
 
 def chunkheader(length):
-    """build a changegroup chunk header"""
+    """return a changegroup chunk header (string)"""
     return struct.pack(">l", length + 4)
 
 def closechunk():
+    """return a changegroup chunk header (string) for a zero-length chunk"""
     return struct.pack(">l", 0)
 
 class nocompress(object):
diff --git a/mercurial/localrepo.py b/mercurial/localrepo.py
--- a/mercurial/localrepo.py
+++ b/mercurial/localrepo.py
@@ -1457,6 +1457,12 @@
         return self.push_addchangegroup(remote, force, revs)
 
     def prepush(self, remote, force, revs):
+        '''Analyze the local and remote repositories and determine which
+        changesets need to be pushed to the remote.  Return a tuple
+        (changegroup, remoteheads).  changegroup is a readable file-like
+        object whose read() returns successive changegroup chunks ready to
+        be sent over the wire.  remoteheads is the list of remote heads.
+        '''
         common = {}
         remote_heads = remote.heads()
         inc = self.findincoming(remote, common, remote_heads, force=force)
@@ -1601,9 +1607,10 @@
                 self.ui.debug("%s\n" % hex(node))
 
     def changegroupsubset(self, bases, heads, source, extranodes=None):
-        """This function generates a changegroup consisting of all the nodes
-        that are descendents of any of the bases, and ancestors of any of
-        the heads.
+        """Compute a changegroup consisting of all the nodes that are
+        descendents of any of the bases and ancestors of any of the heads.
+        Return a chunkbuffer object whose read() method will return
+        successive changegroup chunks.
 
         It is fairly complex as determining which filenodes and which
         manifest nodes need to be included for the changeset to be complete
@@ -1902,8 +1909,9 @@
         return self.changegroupsubset(basenodes, self.heads(), source)
 
     def _changegroup(self, common, source):
-        """Generate a changegroup of all nodes that we have that a recipient
-        doesn't.
+        """Compute the changegroup of all nodes that we have that a recipient
+        doesn't.  Return a chunkbuffer object whose read() method will return
+        successive changegroup chunks.
 
         This is much easier than the previous function as we can assume that
         the recipient has any changenode we aren't sending them.
@@ -1937,6 +1945,7 @@
             return lookuprevlink
 
         def gengroup():
+            '''yield a sequence of changegroup chunks (strings)'''
             # construct a list of all changed files
             changedfiles = set()
 
diff --git a/mercurial/revlog.py b/mercurial/revlog.py
--- a/mercurial/revlog.py
+++ b/mercurial/revlog.py
@@ -1128,7 +1128,8 @@
         return self.node(c)
 
     def group(self, nodelist, lookup, infocollect=None):
-        """calculate a delta group
+        """Calculate a delta group, yielding a sequence of changegroup chunks
+        (strings).
 
         Given a list of changeset revs, return a set of deltas and
         metadata corresponding to nodes. the first delta is