examples: Synchronised comments between SMTP MAIL examples

diff --git a/docs/examples/smtp-mail.c b/docs/examples/smtp-mail.c
index bfc445dc174ad6ceaa2ebd4306619f126e5f538f..ed9524e877efb5c36e193a6c2f4d723485871d4e 100644 (file)
--- a/docs/examples/smtp-mail.c
+++ b/docs/examples/smtp-mail.c
@@ -111,7 +111,7 @@ int main(void)
     curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
     curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
 
-    /* send the message (including headers) */
+    /* Send the message */
     res = curl_easy_perform(curl);
 
     /* Check for errors */
@@ -119,7 +119,7 @@ int main(void)
       fprintf(stderr, "curl_easy_perform() failed: %s\n",
               curl_easy_strerror(res));
 
-    /* free the list of recipients */
+    /* Free the list of recipients */
     curl_slist_free_all(recipients);
 
     /* curl won't send the QUIT command until you call cleanup, so you should be

diff --git a/docs/examples/smtp-ssl.c b/docs/examples/smtp-ssl.c
index 3402ad42b5def7cc4929fd4df0fa85b62931ce65..9a68a7ff9e240b0cb83ab80d778732a264c16cf8 100644 (file)
--- a/docs/examples/smtp-ssl.c
+++ b/docs/examples/smtp-ssl.c
@@ -41,7 +41,7 @@ static const char *payload_text[] = {
   "From: " FROM "(Example User)\r\n",
   "Cc: " CC "(Another example User)\r\n",
   "Message-ID: <dcd7cb36-11db-487a-9f3a-e652a9458efd@rfcpedant.example.org>\r\n",
-  "Subject: SMTP TLS example message\r\n",
+  "Subject: SMTP SSL example message\r\n",
   "\r\n", /* empty line to divide headers from body, see RFC5322 */
   "The body of the message starts here.\r\n",
   "\r\n",
@@ -115,7 +115,12 @@ int main(void)
     curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 0L);
 #endif
 
-    /* Value for envelope reverse-path */
+    /* Note that this option isn't strictly required, omitting it will result in
+     * libcurl sending the MAIL FROM command with empty sender data. All
+     * autoresponses should have an empty reverse-path, and should be directed
+     * to the address in the reverse-path which triggered them. Otherwise, they
+     * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details.
+     */
     curl_easy_setopt(curl, CURLOPT_MAIL_FROM, FROM);
 
     /* Add two recipients, in this particular case they correspond to the
@@ -125,9 +130,9 @@ int main(void)
     recipients = curl_slist_append(recipients, CC);
     curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
 
-    /* In this case, we're using a callback function to specify the data. You
-     * could just use the CURLOPT_READDATA option to specify a FILE pointer to
-     * read from. */
+    /* We're using a callback function to specify the payload (the headers and
+     * body of the message). You could just use the CURLOPT_READDATA option to
+     * specify a FILE pointer to read from. */
     curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
     curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
     curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);

diff --git a/docs/examples/smtp-tls.c b/docs/examples/smtp-tls.c
index 4e610d9acb413d7033b7b4e0d210fb96e19ebde3..4872dbdf117fa3e9a7c94d78a367b6ee564fa4f9 100644 (file)
--- a/docs/examples/smtp-tls.c
+++ b/docs/examples/smtp-tls.c
@@ -117,7 +117,12 @@ int main(void)
      * docs/SSLCERTS for more information. */
     curl_easy_setopt(curl, CURLOPT_CAINFO, "/path/to/certificate.pem");
 
-    /* Value for envelope reverse-path */
+    /* Note that this option isn't strictly required, omitting it will result in
+     * libcurl sending the MAIL FROM command with empty sender data. All
+     * autoresponses should have an empty reverse-path, and should be directed
+     * to the address in the reverse-path which triggered them. Otherwise, they
+     * could cause an endless loop. See RFC 5321 Section 4.5.5 for more details.
+     */
     curl_easy_setopt(curl, CURLOPT_MAIL_FROM, FROM);
 
     /* Add two recipients, in this particular case they correspond to the
@@ -127,9 +132,9 @@ int main(void)
     recipients = curl_slist_append(recipients, CC);
     curl_easy_setopt(curl, CURLOPT_MAIL_RCPT, recipients);
 
-    /* In this case, we're using a callback function to specify the data. You
-     * could just use the CURLOPT_READDATA option to specify a FILE pointer to
-     * read from. */
+    /* We're using a callback function to specify the payload (the headers and
+     * body of the message). You could just use the CURLOPT_READDATA option to
+     * specify a FILE pointer to read from. */
     curl_easy_setopt(curl, CURLOPT_READFUNCTION, payload_source);
     curl_easy_setopt(curl, CURLOPT_READDATA, &upload_ctx);
     curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);