diff --git a/docs/remotes.rst b/docs/remotes.rst
index 1dcbe5d0c..387e9ac27 100644
--- a/docs/remotes.rst
+++ b/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:
 
diff --git a/pygit2/credentials.py b/pygit2/credentials.py
index 39d86eeb8..adefc6c58 100644
--- a/pygit2/credentials.py
+++ b/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.
 
     """
 
diff --git a/pygit2/refspec.py b/pygit2/refspec.py
index 423b72b74..e55171017 100644
--- a/pygit2/refspec.py
+++ b/pygit2/refspec.py
@@ -35,6 +35,7 @@
 
 
 class Refspec(object):
+    """The constructor is for internal use only"""
     def __init__(self, owner, ptr):
         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"""
diff --git a/pygit2/remote.py b/pygit2/remote.py
index 9a582132d..22b365292 100644
--- a/pygit2/remote.py
+++ b/pygit2/remote.py
@@ -293,7 +293,7 @@ def push_refspecs(self, l):
     def add_fetch(self, spec):
         """add_fetch(refspec)
 
-        Add a fetch refspec to the remote"""
+        Add a fetch refspec (str) to the remote"""
 
         err = C.git_remote_add_fetch(self._remote, to_bytes(spec))
         check_error(err)
@@ -301,7 +301,7 @@ def add_fetch(self, spec):
     def add_push(self, spec):
         """add_push(refspec)
 
-        Add a push refspec to the remote"""
+        Add a push refspec (str) to the remote"""
 
         err = C.git_remote_add_push(self._remote, to_bytes(spec))
         check_error(err)