- Patch #72137 by Ber: improved Doxygen of user_mail().

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', ''))) {

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', ''))) {