[PATCH] Document that sasl_client_start() can return SASL_OK

[Christophe Fergeau]

sasl_client_start() can return SASL_OK with some authentication methods
(PLAIN for example), but the documentation is not very consistent about it.
Sometimes it implies that client code only needs to deal with SASL_CONTINUE
and SASL_INTERACT, sometimes it handles SASL_OK in addition to these 2 values.

This commit tries to make the documentation for this return value
consistent.
---
 doc/programming.html    | 6 +++---
 man/sasl_client_start.3 | 9 ++++++---
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/doc/programming.html b/doc/programming.html
index 00fac38..bd30b1c 100644
--- a/doc/programming.html
+++ b/doc/programming.html
@@ -340,7 +340,7 @@ begin the authentication process.
            } while (result==SASL_INTERACT); /* the mechanism may ask us to fill
                                                in things many times. result is 
                                                SASL_CONTINUE on success */
-           if (result!=SASL_CONTINUE) [failure]
+           if (result!=SASL_CONTINUE && result!=SASL_OK) [failure]
 
        
 </pre>
@@ -391,8 +391,8 @@ in IMAP.</li>
 </ol>
 
 Convert the continuation data to binary format (for example, this
-may include base64 decoding it). Perform another step in the
-authentication. 
+may include base64 decoding it). If sasl_client_start() returned
+SASL_CONTINUE, perform another step in the authentication.
 
 <pre>
               do {
diff --git a/man/sasl_client_start.3 b/man/sasl_client_start.3
index a37cff7..533abb5 100644
--- a/man/sasl_client_start.3
+++ b/man/sasl_client_start.3
@@ -64,6 +64,9 @@ upon the security preferences specified earlier. The list of
 mechanisms is typically a list of mechanisms the server supports
 acquired from a capability request.
 
+It returns SASL_OK if no more authentication steps are needed, and
+SASL_CONTINUE if at least one more step is needed.
+
 If SASL_INTERACT is returned the library needs some values to be
 filled in before it can proceed. The prompt_need structure will be
 filled in with requests. The application should fulfill these requests
@@ -102,9 +105,9 @@ contains the name of the chosen SASL mechanism (on success)
 
 sasl_client_start returns an integer which corresponds to one of the
 following codes. SASL_CONTINUE indicates success and that there are
-more steps needed in the authentication. All other return codes
-indicate errors and should either be handled or the authentication
-session should be quit.
+more steps needed in the authentication. SASL_OK indicates that the
+authentication is complete. All other return codes indicate errors and
+should either be handled or the authentication session should be quit.
 
 .SH "CONFORMING TO"
 RFC 4422
-- 
1.8.4.2