Improve documentation of drupal_set_message()

In the attached patch:

1. - * Sets a message which reflects the status of the performed operation.
+ * Sets a message to display to the user.
   
   Tweak the one-line summary to indicate who set messages are for. Since not all messages are, per se, in response to a "performed operation", I removed that clause (but I wouldn't be adamant about that change).
2. + *
+ * Messages are stored in a session variable and displayed in the "System help"
+ * block.
   
   Add a slightly expanded description explaining where set messages go and how they're displayed.
3. + *
+ * Example usage:
+ * @code
+ * drupal_set_message(t('An error occurred and processing did not complete.'), 'error');
+ * @endcode
   
   A simple example never hurts, and it quickly answers the question I most frequently come here to answer: "Is the message string supposed to be translated or not?"
4. - * If the function is called with no arguments, this function returns all set
- * messages without clearing them.
+ * If the function is called without arguments, it returns all set messages
+ * without clearing them.
   
   Grammar/style issue: Use a pronoun instead of repeating the subject in the same sentence.
5. - * @param $message
- *   The message to be displayed to the user. For consistency with other
- *   messages, it should begin with a capital letter and end with a period.
+ * @param string $message
+ *   The translated message to be displayed to the user. For consistency with
+ *   other messages, it should begin with a capital letter and end with a
+ *   period.
   
   Indicate that the message string should be translated. As long as I'm touching every line anyway, add the variable data types.
6. - * @param $type
- *   The type of the message. One of the following values are possible:
+ * @param string $type
+ *   The message's type. Defaults to 'status'. These values are supported:
   
   Make the first sentence more direct. Add the default value of the parameter. Change "possible" to "supported". (You can technically use anything for a type—e.g. 'catastrophe'—it just won't get styled in the theme and such.)
7. - * @param $repeat
+ * @param bool $repeat
  *   If this is FALSE and the message is already set, then the message won't
- *   be repeated.
+ *   be repeated. Defaults to TRUE.
   
   Indicate the default value for the parameter.
8. + *
+ * @return array|null
+ *   A multidimensional array with keys corresponding to the set message types.
+ *   The indexed array values of each contain the set messages for that type.
+ *   Or, if there are no messages set, the function returns NULL.
   
   Specify the return value!
9. + *
+ * @see drupal_get_messages()
+ * @see theme_status_messages()
   
   Link to a couple of related functions.

Thanks for the patch!

A few questions/things to fix:

a)

I do not think this is accurate. system_process_page() puts them in the $messages theme variable, and the I don't think any existing core themes' page.tpl.php put them in a help region (they definitely don't go in a "block" at all, and many themes don't even have a help region).

b) The $message param description should say it's optional.

c) That paragraph from before about it returning all the messages if there is no input... It *always* returns all the messages, and never clears them, whether or not there is input, so maybe it could just be omitted? It's covered in the return value docs anyway.

Looks good! I'll get this committed to 8.x and most likely 7.x shortly.

Automatically closed -- issue fixed for 2 weeks with no activity.