[PATCH 01 of 22] wireproto: document possible return type

[pierre-yves.david at ens-lyon.org]

# HG changeset patch
# User Pierre-Yves David <pierre-yves.david at fb.com>
# Date 1396031862 25200
#      Fri Mar 28 11:37:42 2014 -0700
# Node ID a403855f263738815a7fcc131a0588d742b5f273
# Parent  1dc36565b5cc56e71f8e5a5ac5f97fdd85a4496d
wireproto: document possible return type

The wireprotocole command use a small set of class as return value. We document
the meaning of each of them.

AS my knowledge of wire protocol is fairly shallow, the documentation can
probably use improvement. But this is a better than nothing.

diff --git a/mercurial/wireproto.py b/mercurial/wireproto.py
--- a/mercurial/wireproto.py
+++ b/mercurial/wireproto.py
@@ -325,23 +325,42 @@ class wirepeer(peer.peerrepository):
             opts['four'] = four
         return self._call('debugwireargs', one=one, two=two, **opts)
 
 # server side
 
+# wire protocol command can either return a string or one of this class.
 class streamres(object):
+    """wireproto reply: binary stream
+
+    The call was successful and the result is a stream.
+    Iterable to the `self.gen` attribute to retrieve chunks.
+    """
     def __init__(self, gen):
         self.gen = gen
 
 class pushres(object):
+    """wireproto reply: success with simple integer return
+
+    The call was successful and returned an integer contained in `self.res`.
+    """
     def __init__(self, res):
         self.res = res
 
 class pusherr(object):
+    """wireproto reply: failure
+
+    The call failed. the `self.res` attribut contains the error message.
+    """
     def __init__(self, res):
         self.res = res
 
 class ooberror(object):
+    """wireproto reply: failure of a batch of operation
+
+    During a batch call, something failed, the error message is stored in
+    `self.message`.
+    """
     def __init__(self, message):
         self.message = message
 
 def dispatch(repo, proto, command):
     repo = repo.filtered("served")