Document that $params is available to hook_mail_alter()

This is $message array in DRUPAL-7-0-UNSTABLE-8 when a user is created.

Array
(
    [id] => user_register_admin_created
    [to] => receipient@example.com
    [from] => sender@example.com
    [language] => stdClass Object
        (
            [language] => en
            [name] => English
            [native] => English
            [direction] => 0
            [enabled] => 1
            [plurals] => 0
            [formula] => 
            [domain] => 
            [prefix] => 
            [weight] => 0
            [javascript] => 
        )

    [params] => Array
        (
            [account] => stdClass Object
                (
                    [uid] => 3
                    [name] => dale
                    [pass] => $P$Cha0L3u8gAM0BjrYQ2qxlilSsM17W61
                    [mail] => receipient@example.com
                    [theme] => 
                    [signature] => 
                    [created] => 1249429682
                    [access] => 1249429682
                    [login] => 0
                    [status] => 1
                    [timezone] => America/Los_Angeles
                    [language] => 
                    [picture] => 
                    [init] => receipient@example.com
                    [data] => a:1:{s:5:"block";a:0:{}}
                    [block] => Array
                        (
                        )

                    [roles] => Array
                        (
                            [2] => authenticated user
                        )

                    [password] => dale
                )

        )

    [subject] => This is the subject line
    [body] => Array
        (
            [0] => This is the message text
        )

    [headers] => Array
        (
            [MIME-Version] => 1.0
            [Content-Type] => text/plain; charset=UTF-8; format=flowed; delsp=yes
            [Content-Transfer-Encoding] => 8Bit
            [X-Mailer] => Drupal
            [Errors-To] => sender@example.com
            [Return-Path] => sender@example.com
            [Sender] => sender@example.com
            [From] => sender@example.com
        )

)

Attached patch updates the function comments adding the 'params' and 'language' keys. Also updated some of the text to make it more compliant to the style guidelines.

/**
 * Perform alterations before an email is sent by Drupal. For example:
 * add a common site footer, an additional message header, or
 * modify the mesage text.
 *
 * @param $message
 *   An array containing the message data. Keys in this
 *   array include:
 *  - 'id':
 *     An id to identify the mail sent. Look at module source code
 *     or drupal_mail() for possible id values.
 *  - 'to':
 *     The address or addresses the message will be sent to. The
 *     formatting of this string must comply with RFC 2822.
 *  - 'from':
 *     The address the message will be marked as being from, which is
 *     either a custom address or the site-wide default email address.
 *  - 'subject':
 *     Subject of the email to be sent. This must not contain any newline
 *     characters, or the email may not be sent properly.
 *  - 'body':
 *     An array of lines containing the message to be sent. Drupal will format
 *     the line endings for RFC 2822.
 *  - 'headers':
 *     Associative array containing mail headers, such as From, Sender,
 *     MIME-Version, Content-Type, etc.
 *  - 'params': An array of parameters supplied by the caller of drupal_mail().
 *  - 'language': A language object supplied by the caller of drupal_mail().
 *
 * @see drupal_mail()
 */

Emma Jane did a quick look and gave feedback via IRC. Newly updated text:

/**
 * Perform alterations before an email is sent by Drupal. For example:
 * add a common site footer, an additional message header, or * modify the
 * mesage text.
 *
 * @param $message
 *   An array containing the message data. Keys in this array include:
 *  - 'id':
 *     An id identifying the message.
 *  - 'to':
 *     The address or addresses the message will be sent to. The
 *     formatting of this string must comply with RFC 2822.
 *  - 'from':
 *     The address the message will be marked as being from, which is
 *     either a custom address or the site-wide default email address.
 *  - 'subject':
 *     Subject of the email to be sent. This must not contain any newline
 *     characters, or the email may not be sent properly.
 *  - 'body':
 *     An array of lines containing the message to be sent. Message body line
 *     endings are formatted for RFC 2822 compliance.
 *  - 'headers':
 *     Associative array containing mail headers, such as From, Sender,
 *     MIME-Version, Content-Type, etc.
 *  - 'params': An array of parameters supplied by the caller of drupal_mail().
 *  - 'language': A language object supplied by the caller of drupal_mail().
 *
 * @see drupal_mail()
 */

I noticed that "mesage" is misspelled on the third line, and there seems to be a little line-break inconsistency. Otherwise, it makes perfect sense to me!

Here's the patch with "message" and line-breaks fixed.

* add a common site footer, an additional message header, or modify the
* message text.

and

*  - 'params':
*     An array of parameters supplied by the caller of drupal_mail().
*  - 'language':
*     A language object supplied by the caller of drupal_mail().

to match "'id':" line above.

Rerolled patch with corrected text

Whoops! Sorry about that.

+++ modules/system/system.api.php	5 Aug 2009 03:13:15 -0000
@@ -590,32 +590,35 @@ function hook_profile_alter(&$account) {
+ * add a common site footer, an additional message header, or * modify the

"site footer" seems odd, maybe just "footer".

Seems to be an extra * before modify.

Good catch, errant * removed. Text updated. 5th time a charm?

@gpk: Regarding the initial function description being one line. I checked the existing api doc and there is no consistency, and I can't find a writing guideline reference. If you know where this is specified, would appreciate the URL. Since the first paragraph appears in the hook summary, I suspect the guideline is understandability. In this specific case, I agree with you.

Regarding simply adding the new parameters, it started that way and one of the doc team suggested further improvements so here we are :-)

Your comments made me take a closer look at the actual function. This description should be more accurate all round.

/**
 * Alter an email message created with the drupal_mail() function.
 *
 * hook_mail_alter() allows modification of email messages created and sent
 * with drupal_mail(). Usage examples include adding and/or changing message
 * text, message fields, and message headers.
 *
 * Email messages sent using functions other than drupal_mail() will not
 * invoke hook_mail_alter(). While Drupal core modules use drupal_mail() for
 * email messages, contributed modules using other functions will not be
 * subject to this hook.
 *
 * @param $message
 *   An array containing the message data. Keys in this array include:
 *  - 'id':
 *     The drupal_mail() id of the message.
 *  - 'to':
 *     The address or addresses the message will be sent to. The
 *     formatting of this string must comply with RFC 2822.
 *  - 'from':
 *     The address the message will be marked as being from, which is
 *     either a custom address or the site-wide default email address.
 *  - 'subject':
 *     Subject of the email to be sent. This must not contain any newline
 *     characters, or the email may not be sent properly.
 *  - 'body':
 *     An array of strings containing the message text. The message body is
 *     created by concatenating the individual array strings into a single text 
 *     string using "\n\n" as a separator.
 *  - 'headers':
 *     Associative array containing mail headers, such as From, Sender,
 *     MIME-Version, Content-Type, etc.
 *  - 'params':
 *     An array of optional parameters used to build the message before
 *     hook_mail_alter() is invoked.
 *  - 'language':
 *     The language object used to build the message before hook_mail_alter()
 *     is invoked.
 *
 * @see drupal_mail()
 */

Doc header conventions are found here: http://drupal.org/node/1354

This documentation is good, and a vast improvement over the previous doc.

Sorry, finger slipped.

Wow! Great job on this!! Some comments...

+++ modules/system/system.api.php	5 Aug 2009 20:06:00 -0000
@@ -590,32 +590,45 @@ function hook_profile_alter(&$account) {
+ * Email messages sent using functions other than drupal_mail() will not
+ * invoke hook_mail_alter(). While Drupal core modules use drupal_mail() for
+ * email messages, contributed modules using other functions will not be
+ * subject to this hook.
  *

This sounds scary. Could you explain this more? Under what circumstances would a contrib module not be calling drupal_mail()?

+++ modules/system/system.api.php	5 Aug 2009 20:06:00 -0000
@@ -590,32 +590,45 @@ function hook_profile_alter(&$account) {
- *     An id to identify the mail sent. Look at module source code
- *     or drupal_mail() for possible id values.
- *   - 'to'
+ *     The drupal_mail() id of the message.

I actually think the old text was more helpful here. Or maybe not helpful, but it gave me a clue where to start looking.

Since this is the most important aspect of this function, we should probably take the opportunity to document it well here.

+++ modules/system/system.api.php	5 Aug 2009 20:06:00 -0000
@@ -590,32 +590,45 @@ function hook_profile_alter(&$account) {
+ *  - 'params':
+ *     An array of optional parameters used to build the message before
+ *     hook_mail_alter() is invoked.

What sort of parameters?

This review is powered by Dreditor.

webchick: This sounds scary. Could you explain this more? Under what circumstances would a contrib module not be calling drupal_mail()?

I wouldn't attempt to second-guess a contrib author's decision process on why they did or didn't use drupal_mail()! :-) The text was added to make it clear there could be situations where messages could be sent without using hook_mail()/drupal_mail() Paragraph updated to read:

 * Email messages sent using functions other than drupal_mail() will not
 * invoke hook_mail_alter(). For example, a contributed module directly
 * calling the drupal_mail_send() or PHP mail() function will not invoke this
 * hook. All core modules use drupal_mail() for messaging, it is best practice
 * but not manditory in contributed modules.

For "id" I've added the sentence, "Look at module source code or drupal_mail() for possible id values.", back in.

For "params" I've used a variation of the language used in the hook_mail() description: "'params': An array of optional parameters supplied by the caller of drupal_mail() that is used to build the message before hook_mail_alter() is invoked." If params is going to be documented, I'd recommend documenting it in hook_mail().

I read through this and it looked great. Committed.