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