hook_mail() doc should state it's only called on one module not all modules

That is an excellent suggestion. The documentation should be fixed in Drupal 7 first, then the fix ported back to Drupal 6.

This is also a good project for a novice doc contributor

I'm not sure I'm being clear enough here, but patch attached.

The message looks good, but you should also put the key description inline with the key.

From : http://drupal.org/node/1354#lists

Each list item starts with the key, followed by a colon, followed by a space, followed by the key description. The key description starts with a capital letter and ends with a period.

Good catch. When I went back, I noticed the indentation on that list was off as well, so fixed that at the same time. New patch attached.

#5: 945456-5.patch queued for re-testing.

+ * Note that hook_mail(), unlike hook_mail_alter(), is only called by its own
+ * module, not all modules.

called by its own module -> called on the $module argument to drupal_mail() (or something to that effect)?

As long as you are cleaning up the $message doc:

- "Keys in this array include:" -> "Elements in this array include:"
- "id" -> "ID" in text (obviously don't change the array keys). "id" is a psychological term (ego, superego, and id). ID is an abbreviation for identification or identifier. At least according to several dictionaries I checked.

So I debated between "is only acted on by the caller of drupal_mail()" and your version, and I think ultimately your version is more precise and clear. Rerolled that version along with the two other doc changes for review.

At some point I'll remember to change the status when I attach a patch.

This is backwards:

+ *   - ID: An id to identify the mail sent. Look at module source code
  *     or drupal_mail() for possible id values.

It should be
-id: An ID to identify the mail sent.

Other than that, the above patch is OK I think...

And you totally said that too - I just completely misread it. My mistake! Fixed and attached.

Looks good to me, thanks!

Committed to CVS HEAD. Thanks.