Improve documentation of drupal_set_message()

Added "Patch to follow."

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.

Oops. I got an extra blank docblock line at the end there.

a) You're right! How about "Messages are stored in a session variable and displayed in page.tpl.php via the $messages theme variable."?

b) Right again. In fact, now that you mention it, all the arguments are optional.

c) I agree.

Updated patch attached.