email: Provided extra comments following recent pop3/imap fixes

Provided additional clarification about the logic of the authenticate()
functions following commit 6b6bdc83bd and b4270a9af1.

lib/imap.c

@@ -519,7 +519,7 @@ static CURLcode imap_authenticate(struct connectdata *conn)
   const char *mech = NULL;
   imapstate authstate = IMAP_STOP;
 
-  /* Check supported authentication mechanisms by decreasing order of
+  /* Calculate the supported authentication mechanism by decreasing order of
      security */
 #ifndef CURL_DISABLE_CRYPTO_AUTH
   if(imapc->authmechs & SASL_MECH_DIGEST_MD5) {
@@ -554,6 +554,7 @@ static CURLcode imap_authenticate(struct connectdata *conn)
   }
 
   if(mech) {
+    /* Perform SASL based authentication */
     const char *str = getcmdid(conn);
 
     result = imap_sendf(conn, str, "%s AUTHENTICATE %s", str, mech);
@@ -562,10 +563,12 @@ static CURLcode imap_authenticate(struct connectdata *conn)
       state(conn, authstate);
   }
   else if(!imapc->login_disabled)
+    /* Perform clear text authentication */
     result = imap_state_login(conn);
   else {
+    /* Other mechanisms not supported */
     infof(conn->data, "No known authentication mechanisms supported!\n");
-    result = CURLE_LOGIN_DENIED; /* Other mechanisms not supported */
+    result = CURLE_LOGIN_DENIED;
   }
 
   return result;

lib/pop3.c

@@ -458,7 +458,7 @@ static CURLcode pop3_authenticate(struct connectdata *conn)
   const char *mech = NULL;
   pop3state authstate = POP3_STOP;
 
-  /* Check supported authentication mechanisms by decreasing order of
+  /* Calculate the supported authentication mechanism by decreasing order of
      security */
   if(pop3c->authtypes & POP3_TYPE_SASL) {
 #ifndef CURL_DISABLE_CRYPTO_AUTH
@@ -495,6 +495,7 @@ static CURLcode pop3_authenticate(struct connectdata *conn)
   }
 
   if(mech) {
+    /* Perform SASL based authentication */
     result = Curl_pp_sendf(&pop3c->pp, "AUTH %s", mech);
 
     if(!result)
@@ -502,13 +503,16 @@ static CURLcode pop3_authenticate(struct connectdata *conn)
   }
 #ifndef CURL_DISABLE_CRYPTO_AUTH
   else if(pop3c->authtypes & POP3_TYPE_APOP)
+    /* Perform APOP authentication */
     result = pop3_state_apop(conn);
 #endif
   else if(pop3c->authtypes & POP3_TYPE_CLEARTEXT)
+    /* Perform clear text authentication */
     result = pop3_state_user(conn);
   else {
+    /* Other mechanisms not supported */
     infof(conn->data, "No known authentication mechanisms supported!\n");
-    result = CURLE_LOGIN_DENIED; /* Other mechanisms not supported */
+    result = CURLE_LOGIN_DENIED;
   }
 
   return result;

lib/smtp.c

@@ -373,8 +373,8 @@ static CURLcode smtp_authenticate(struct connectdata *conn)
     return result;
   }
 
-  /* Check supported authentication mechanisms by decreasing order of
-     security */
+  /* Calculate the supported authentication mechanism, by decreasing order of
+     security, as well as the initial response where appropriate */
 #ifndef CURL_DISABLE_CRYPTO_AUTH
   if(smtpc->authmechs & SASL_MECH_DIGEST_MD5) {
     mech = "DIGEST-MD5";
@@ -417,11 +417,13 @@ static CURLcode smtp_authenticate(struct connectdata *conn)
                                             conn->passwd, &initresp, &len);
   }
   else {
+    /* Other mechanisms not supported */
     infof(conn->data, "No known authentication mechanisms supported!\n");
-    result = CURLE_LOGIN_DENIED; /* Other mechanisms not supported */
+    result = CURLE_LOGIN_DENIED;
   }
 
   if(!result) {
+    /* Perform SASL based authentication */
     if(initresp &&
        strlen(mech) + len <= 512 - 8) { /* AUTH <mech> ...<crlf> */
        result = Curl_pp_sendf(&smtpc->pp, "AUTH %s %s", mech, initresp);
@@ -435,6 +437,7 @@ static CURLcode smtp_authenticate(struct connectdata *conn)
       if(!result)
         state(conn, state1);
     }
+
     Curl_safefree(initresp);
   }