update drupal_set_message docs

By convention, it should begin with a cap letter and end with a period. The sentence could be reworded to make it clear that's a convention.

How's this?

The patch looks like it's editing watchdog() not drupal_set_message(). That said I didn't try applying it.

The new comment sounds kind of awkward. How about something like "The message to be displayed to the visitor. For consistency with other messages you should begin with a capital letter and end with period."

I like the proposed description by drewish; however, 'visitor' should be changed to 'user' as drupal_set_message applies to more than just a site's visitors (e.g., admins, editors, other roles, etc...)

gbrands, I agree. Patch attached.

drewish, the patch definitely changes the comment block above drupal_set_message(). I'm guessing git shows watchdog() there because it is the last function declaration previous to the changed lines. I rolled the patch with plain old git diff.

Looks good to me! Let's get this into d8 and d7.

Committed to 8.x. Moving to 7.x. Thanks for the clarification.

Oops, missed a grammatical error. Sorry about that.

Whoops, I missed that too, thanks! Please commit to d8 and then we need to combine the two patches for d7.

Committed to 7.x and 8.x.