Improve documentation of drupal_get_messages()

As a natural companion to #1697750: Improve documentation of drupal_set_message(), the docblock for drupal_get_messages() needs improvement. It has at least the following issues:

• It doesn't specify the parameter or return types.
• It doesn't specify all of the parameter defaults or acceptable values.
• It doesn't make it clear whether $clear_queue will clear all messages or just those of the type specified in the $type parameter.
• It doesn't @see closely-related functions.
• The grammar and English style can be improved a little.

Patch to follow.