[development] QA: Consensus on comment formatting

[Derek Wright]

On Jan 8, 2007, at 4:44 AM, Karen Stevenson wrote:

> +1 for being gentle with developers whose modules don't meet these  
> standards : -)

these would just be the official style guidelines for core.  as  
always, the goal is for contrib to live up to core's high standards,  
but it's not a requirement.


On Jan 8, 2007, at 7:43 AM, Angela Byron wrote:
> Does this:
>
>>   // @todo These queries are very expensive, see http://drupal.org/ 
>> node/105639.
>
> ...actually work and get parsed by doxygen?? I thought doxygen only  
> worked on function headers. This would make @todo less useful,

from what i understand from the doxygen docs about @todo [1]:

"Starts a paragraph where a TODO item is described. The description  
will also add an item to a separate TODO list. The two instances of  
the description will be cross-referenced. Each item in the TODO list  
will be preceded by a header that indicates the origin of the item."

in addition to special formatting in a /** function */ block, it also  
auto-generates a separate todo.html page, for example (thanks, google):

http://www.portaudio.com/docs/v19-doxydocs/todo.html


furthermore, according to [2], doxygen supports putting doxygen  
commands on a single line using /// (just like doc++ and a few  
similar systems).  for example:

/**
  * Do a nasty thing.
  *
  * Blah, blah ...
  *
  * @param ...
  *
  * @return ...
  */
function nasty_thing() {
   if (something crazy) {
     /// @todo This query is very expensive, see http://drupal.org/ 
node/105639.
     $query = db_query(...);
   }
}

i don't have a good test site to play with, but that will a) keep the  
@todo as close to the thing it's trying to describe and b) should  
still get auto-formatted in some nice way by doxygen, either in the  
resulting html docs for that function, or at the very least, as  
another item in the todo.html file.  it's visually eye-catching, easy  
to grep/search for, and given that there's already *some* built-in  
support for @todo, we should stick with "/// @todo" instead of "//  
TODO:"

-derek


[1] http://www.stack.nl/~dimitri/doxygen/commands.html#cmdtodo

[2] http://www.stack.nl/~dimitri/doxygen/docblocks.html