From 9d5d9ab009088b1f021a97e019b8de00e0249091 Mon Sep 17 00:00:00 2001
From: Dries Buytaert <dries@buytaert.net>
Date: Fri, 7 Jul 2006 18:49:13 +0000
Subject: [PATCH] - Patch #72137 by Ber: improved Doxygen of user_mail().

---
 modules/user.module      | 23 ++++++++++++++++++++++-
 modules/user/user.module | 23 ++++++++++++++++++++++-
 2 files changed, 44 insertions(+), 2 deletions(-)

diff --git a/modules/user.module b/modules/user.module
index d53bf74aa4e..91f77ba3452 100644
--- a/modules/user.module
+++ b/modules/user.module
@@ -382,7 +382,28 @@ function user_is_blocked($name) {
 }
 
 /**
- * Send an e-mail message.
+ * Send an e-mail message, using Drupal variables and default settings.
+ * More information in the <a href="http://php.net/manual/en/function.mail.php">
+ * PHP function reference for mail()</a>
+ * @param $mail
+ *  The mail address or addresses where the message will be send to. The
+ *  formatting of this string must comply with RFC 2822. Some examples are:
+ *    user@example.com
+ *    user@example.com, anotheruser@example.com
+ *    User <user@example.com>
+ *    User <user@example.com>, Another User <anotheruser@example.com>
+ *  @param $subject
+ *    Subject of the e-mail to be sent. This must not contain any newline
+ *    characters, or the mail may not be sent properly.
+ *  @param $message
+ *    Message to be sent. Drupal will format the correct line endings for you.
+ *  @param $header
+ *    String to be inserted at the end of the e-mail header. This is typically
+ *    used to add extra headers (From, Cc, and Bcc). Multiple extra headers
+ *    should be separated with a CRLF (\r\n).
+ *    <em>When sending mail, the mail must contain a From header.</em>
+ * @return Returns TRUE if the mail was successfully accepted for delivery,
+ *    FALSE otherwise.
  */
 function user_mail($mail, $subject, $message, $header) {
   if (variable_get('smtp_library', '') && file_exists(variable_get('smtp_library', ''))) {
diff --git a/modules/user/user.module b/modules/user/user.module
index d53bf74aa4e..91f77ba3452 100644
--- a/modules/user/user.module
+++ b/modules/user/user.module
@@ -382,7 +382,28 @@ function user_is_blocked($name) {
 }
 
 /**
- * Send an e-mail message.
+ * Send an e-mail message, using Drupal variables and default settings.
+ * More information in the <a href="http://php.net/manual/en/function.mail.php">
+ * PHP function reference for mail()</a>
+ * @param $mail
+ *  The mail address or addresses where the message will be send to. The
+ *  formatting of this string must comply with RFC 2822. Some examples are:
+ *    user@example.com
+ *    user@example.com, anotheruser@example.com
+ *    User <user@example.com>
+ *    User <user@example.com>, Another User <anotheruser@example.com>
+ *  @param $subject
+ *    Subject of the e-mail to be sent. This must not contain any newline
+ *    characters, or the mail may not be sent properly.
+ *  @param $message
+ *    Message to be sent. Drupal will format the correct line endings for you.
+ *  @param $header
+ *    String to be inserted at the end of the e-mail header. This is typically
+ *    used to add extra headers (From, Cc, and Bcc). Multiple extra headers
+ *    should be separated with a CRLF (\r\n).
+ *    <em>When sending mail, the mail must contain a From header.</em>
+ * @return Returns TRUE if the mail was successfully accepted for delivery,
+ *    FALSE otherwise.
  */
 function user_mail($mail, $subject, $message, $header) {
   if (variable_get('smtp_library', '') && file_exists(variable_get('smtp_library', ''))) {