[PATCH] localrepo: attempt to document return values of push-related methods

[Greg Ward]

# HG changeset patch
# User Greg Ward <greg-hg at gerg.ca>
# Date 1263513800 18000
# Branch stable
# Node ID cdc604a63cbafe54675aeee33d69a98768809817
# Parent  cd3e5c47d6631dc5eccaa5ee043ef1905ded8c8b
localrepo: attempt to document return values of push-related methods.

This information is incomplete because the return values of
push-related methods are, frankly, inscrutable and nearly
incomprehensible.  I would like some feedback from someone who
actually understands this stuff before this patch gets pushed. ;-)

diff --git a/mercurial/httprepo.py b/mercurial/httprepo.py
--- a/mercurial/httprepo.py
+++ b/mercurial/httprepo.py
@@ -201,6 +201,8 @@
         return util.chunkbuffer(zgenerator(f))
 
     def unbundle(self, cg, heads, source):
+        '''Send a bundle for the remote to unbundle.  Return an integer
+        (HTTP response code?).'''
         # have to stream bundle to a temp file because we do not have
         # http 1.1 chunked transfer.
 
diff --git a/mercurial/localrepo.py b/mercurial/localrepo.py
--- a/mercurial/localrepo.py
+++ b/mercurial/localrepo.py
@@ -1440,6 +1440,8 @@
             lock.release()
 
     def push(self, remote, force=False, revs=None):
+        '''Push outgoing changesets (limited by revs) from the current
+        repository to remote.  Return value is apparently meaningless.'''
         # there are two ways to push to remote repo:
         #
         # addchangegroup assumes local user can lock remote
@@ -1567,17 +1569,27 @@
         return cg, remote_heads
 
     def push_addchangegroup(self, remote, force, revs):
+        '''Push a changegroup by locking the remote and sending the
+        addchangegroup command to it.  Used for local and old ssh repos.
+        Return value is inconsistent and probably meaningless.'''
+
         lock = remote.lock()
         try:
             ret = self.prepush(remote, force, revs)
             if ret[0] is not None:
                 cg, remote_heads = ret
+                # wtf: in this case, we return an integer...
                 return remote.addchangegroup(cg, 'push', self.url())
+            # ... but here we return the list of remote heads from prepush()
             return ret[1]
         finally:
             lock.release()
 
     def push_unbundle(self, remote, force, revs):
+        '''Push a changegroup by unbundling it on the remote.  Used for new
+        ssh and http repos.  Return value is inconsistent and probably
+        meaningless.'''
+
         # local repo finds heads on server, finds out what revs it
         # must push.  once revs transferred, if server finds it has
         # different heads (someone else won commit/push race), server
@@ -1587,7 +1599,9 @@
         if ret[0] is not None:
             cg, remote_heads = ret
             if force: remote_heads = ['force']
+            # wtf: here, we return a meaningless integer...
             return remote.unbundle(cg, remote_heads, 'push')
+        # ...but here we return the list of remote heads from prepush()
         return ret[1]
 
     def changegroupinfo(self, nodes, source):
@@ -1970,7 +1984,7 @@
     def addchangegroup(self, source, srctype, url, emptyok=False):
         """add changegroup to repo.
 
-        return values:
+        return an integer:
         - nothing changed or no source: 0
         - more heads than before: 1+added heads (2..n)
         - less heads than before: -1-removed heads (-2..-n)
diff --git a/mercurial/sshrepo.py b/mercurial/sshrepo.py
--- a/mercurial/sshrepo.py
+++ b/mercurial/sshrepo.py
@@ -215,6 +215,8 @@
         return self.do_cmd("changegroupsubset", bases=bases, heads=heads)
 
     def unbundle(self, cg, heads, source):
+        '''Send a bundle for the remote to unbundle.  Return an apparently
+        meaningless integer.'''
         d = self.call("unbundle", heads=' '.join(map(hex, heads)))
         if d:
             # remote may send "unsynced changes"
@@ -240,6 +242,8 @@
             self.abort(error.ResponseError(_("unexpected response:"), r))
 
     def addchangegroup(self, cg, source, url):
+        '''Send a changegroup to the remote.  Return an apparently
+        meaningless integer.'''
         d = self.call("addchangegroup")
         if d:
             self.abort(error.RepoError(_("push refused: %s") % d))