[PATCH 1/5] docs: minor tweaks to credentials API
These are in response to Junio's comments:
1. Clarify how credential rejection works (first we call
helpers, then we clear fields, so helpers get fields). 2. Clarify quoting of keys/values returned from helpers.
Signed-off-by: Jeff King <peff@peff.net>
---
Documentation/technical/api-credentials.txt | 16 ++++++++++------
1 files changed, 10 insertions(+), 6 deletions(-)
diff --git a/Documentation/technical/api-credentials.txt b/Documentation/technical/api-credentials.txt
index 335a007..b2eb24c 100644
--- a/Documentation/technical/api-credentials.txt
+++ b/Documentation/technical/api-credentials.txt
@@ -48,10 +48,11 @@ Functions
`credential_reject`::
Inform the credential subsystem that the provided credentials
- have been rejected. This will clear the username and password
- fields in `struct credential`, as well as notify any helpers of
- the rejection (which may, for example, purge the invalid
- credentials from storage).
+ have been rejected. This will notify any helpers of the
+ rejection (which allows them to, for example, purge the invalid
+ credentials from storage), and then clear the username and
+ password fields in `struct credential`. It can then be
+ `credential_fill`-ed again.
`credential_getpass`::
@@ -98,8 +99,11 @@ command line:
The helper should produce a list of items on stdout, each followed by a
newline character. Each item should consist of a key-value pair, separated
-by an `=` (equals) sign. The value may contain any bytes except a
-newline. When reading the response, git understands the following keys:
+by an `=` (equals) sign. The key can contain any bytes except `=` or
+newline. The value may contain any bytes except a newline. In both
+cases, all bytes are treated as-is (i.e., there is no quoting, and one
+cannot transmit a value with newline in it). When reading the response,
+git understands the following keys:
`username`::
--
1.7.6.252.ge9c18
Jeff King <peff@peff.net>