[development] QA: Consensus on comment formatting

[Angela Byron]

Hey, folks!

In doing a bunch of last minute clean-up patches for the 5.x release  
tonight with the help of Doug Green's lovely Coder module (http:// 
drupal.org/project/coder), and ran into the area of comment conformity.

Awhile back, Nedjo made a valiant attempt to bring order to the chaos  
of the way comments are written in Drupal (http://drupal.org/node/ 
72240). He lays out some rules there which I think are great and  
awesome, and seem to fit the way we do things generally in Drupal.

However, Dries posted (rightly) that we should come to consensus on  
this, and document it, before enforcing it.

So! Anyone have a problem with these rules:

* Comments are full sentences ending in periods.
* There is space between %param and %return sections in function  
documentation (do we want this? sometimes we do it, sometimes not).
* Function documentation begins with a single sentence in the form  
"Do such and such." rather than "Does such and such.", and has a  
space before any further comments.
* Where we have a Note: it is not all caps.
* Spelling, grammar, punctuation corrections.

And if so, I'll bite you. ;P haha, j/k. No, if so, please make your  
case as to why one or more of these _shouldn't_ be the way Nedjo  
specifies here.

I'll commit to rolling patches for fixing this, if not for 5.x then  
for 6.x.

-Angie