Clean up code comments and documentation for spelling, consistency, etc.

I've made some minor additions to the Doxygen formatting conventions handbook page, http://drupal.org/node/1354, about capitalization and blank lines. Most of the rest of what we need is already covered. I tried to post a comment on the Coding standards page, http://drupal.org/node/318, but got a validation error (and don't have edit access to the page), so here's the proposed additions to the "Comments" section:

Non-documentation comments should use capitalized sentences with punctuation and should be on a separate line immediately before the code line or block they reference. For example:

// Unselect all other contact categories.
db_query('UPDATE {contact} SET selected = 0');

If each line of a list needs a separate comment, the comments may be given on the same line and may be formatted to a uniform indent for readability.

All caps are used in comments only when referencing constants, e.g., TRUE.

So the changes and corrections would be:

* Comments are full sentences ending in periods, and are on their own line unless they are documenting lists.
* There is no blank line between %param and %return sections in function documentation.
* Function documentation begins with a single sentence in the form "Do such and such." rather than "Does such and such.", and has a blank line before any further comments.
* @file documentation begins with a sentence in present tense, and has a blank line before any further comments.
* Eliminate inappropriate uses of all caps, e.g, NOTE.
* Spelling, grammar, punctuation corrections.

Here's a partial patch. I've gone through the .inc files but haven't yet made more than a first pass for a couple of things through the.module files. I'm not going to be able to work on this for the next week and a half, so if anyone has an idle moment and wants to push this further, please do!