From fc0cdaebd6a4ecc92cc3ca59db755a394bde145d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Mart=C3=ADn=20Nieto?= <cmn@dwim.me>
Date: Wed, 26 Mar 2014 14:03:29 +0100
Subject: [PATCH] Remote: add documentation for credentials

---
 docs/remotes.rst      | 16 ++++++++++++++++
 pygit2/credentials.py |  4 ++--
 src/remote.c          | 13 ++++++++++++-
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/docs/remotes.rst b/docs/remotes.rst
index f77bd73..58ab8ef 100644
--- a/docs/remotes.rst
+++ b/docs/remotes.rst
@@ -52,3 +52,19 @@ The Refspec type
 .. automethod:: pygit2.Refspec.dst_matches
 .. automethod:: pygit2.Refspec.transform
 .. automethod:: pygit2.Refspec.rtransform
+
+Credentials
+================
+
+.. automethod:: pygit2.Remote.credentials
+
+There are two types of credentials: username/password and SSH key
+pairs. Both :py:class:`pygit2.UserPass` and :py:class:`pygit2.Keypair`
+are callable objects, with the appropriate signature for the
+credentials callback. They will ignore all the arguments and return
+themselves. This is useful for scripts where the credentials are known
+ahead of time. More complete interfaces would want to look up in their
+keychain or ask the user for the data to use in the credentials.
+
+.. autoclass:: pygit2.UserPass
+.. autoclass:: pygit2.Keypair
diff --git a/pygit2/credentials.py b/pygit2/credentials.py
index a3a3c25..dad966b 100644
--- a/pygit2/credentials.py
+++ b/pygit2/credentials.py
@@ -33,7 +33,7 @@ class UserPass(CredUsernamePassword):
     """Username/Password credentials
 
     This is an object suitable for passing to a remote's credentials
-    callback.
+    callback and for returning from said callback.
 
     """
 
@@ -44,7 +44,7 @@ class Keypair(CredSshKey):
     """SSH key pair credentials
 
     This is an object suitable for passing to a remote's credentials
-    callback.
+    callback and for returning from said callback.
 
     """
 
diff --git a/src/remote.c b/src/remote.c
index 9c7cce2..65a195e 100644
--- a/src/remote.c
+++ b/src/remote.c
@@ -705,7 +705,18 @@ PyGetSetDef Remote_getseters[] = {
 
 PyMemberDef Remote_members[] = {
     MEMBER(Remote, progress, T_OBJECT_EX, "Progress output callback"),
-    MEMBER(Remote, credentials, T_OBJECT_EX, "Credentials callback"),
+    MEMBER(Remote, credentials, T_OBJECT_EX,
+  "credentials(url, username_from_url, allowed_types) -> credential\n"
+  "\n"
+  "Credentials callback\n"
+  "\n"
+  "If the remote server requires authentication, this function will\n"
+  "be called and its return value used for authentication.\n"
+  "\n"
+  ":param str url: The url of the remote\n"
+  ":param username_from_url: Username extracted from the url, if any\n"
+  ":type username_from_url: str or None\n"
+  ":param int allowed_types: credential types supported by the remote "),
     MEMBER(Remote, transfer_progress, T_OBJECT_EX, "Transfer progress callback"),
     MEMBER(Remote, update_tips, T_OBJECT_EX, "update tips callback"),
     {NULL},