Remote doc improvements

docs/remotes.rst

@@ -32,6 +32,10 @@ This class contains the data which is available to us during a fetch.
 The Refspec type
 ===================
 
+Refspecs objects are not constructed directly, but returned by
+:meth:`pygit2.Remote.get_refspec`.  To create a new a refspec on a Remote, use
+:meth:`pygit2.Remote.add_fetch` or :meth:`pygit2.Remote.add_push`.
+
 .. autoclass:: pygit2.refspec.Refspec
    :members:
 

pygit2/credentials.py

@@ -65,7 +65,8 @@ class Keypair(object):
         remote server
     :param str pubkey: the path to the user's public key file
     :param str privkey: the path to the user's private key file
-    :param str passphrase: the password used to decrypt the private key file
+    :param str passphrase: the password used to decrypt the private key file,
+        or empty string if no passphrase is required.
 
     """
 

pygit2/refspec.py

@@ -36,6 +36,7 @@
 
 class Refspec(object):
     def __init__(self, owner, ptr):
+        """The constructor is for internal use only"""
         self._owner = owner
         self._refspec = ptr
 
@@ -95,7 +96,7 @@ def transform(self, ref):
         return self._transform(ref, C.git_refspec_transform)
 
     def rtransform(self, ref):
-        """transform(str) -> str
+        """rtransform(str) -> str
 
         Transform a reference name according to this refspec from the lhs
         to the rhs"""

pygit2/remote.py

@@ -83,22 +83,20 @@ def sideband_progress(self, string):
         pass
 
     def credentials(self, url, username_from_url, allowed_types):
-        """Credentials callback
+        """credentials(url, username_from_url, allowed_types) -> Credential
+
+        Credentials callback
 
         If the remote server requires authentication, this function will
         be called and its return value used for authentication. Override
         it if you want to be able to perform authentication.
 
-        Parameters:
-
-        - url (str) -- The url of the remote.
+        :param str url: The url of the remote.
 
-        - username_from_url (str or None) -- Username extracted from the url,
-          if any.
+        :param str|None username_from_url: Username extracted from the
+            url, if any.
 
-        - allowed_types (int) -- Credential types supported by the remote.
-
-        Return value: credential
+        :param int allowed_types: Credential types supported by the remote.
         """
         pass
 
@@ -293,15 +291,21 @@ def push_refspecs(self, l):
     def add_fetch(self, spec):
         """add_fetch(refspec)
 
-        Add a fetch refspec to the remote"""
+        Add a fetch refspec to the remote
+
+        :param str refspec: fetch refspec to add
+        """
 
         err = C.git_remote_add_fetch(self._remote, to_bytes(spec))
         check_error(err)
 
     def add_push(self, spec):
         """add_push(refspec)
 
-        Add a push refspec to the remote"""
+        Add a push refspec to the remote
+
+        :param str refspec: push refspec to add
+        """
 
         err = C.git_remote_add_push(self._remote, to_bytes(spec))
         check_error(err)