@todo directive

[dented42]

it would be nice to have some sort of 'todo' declaration with that would cause a warning to be generated in the output log, similar to when an undocumented member is encountered and --keep-undocumented-members is set.

I'm using a shell script build phase and the Xcode log format so that Xcode tells me when I've missed documenting an item. I can put a large TODO in all caps (or something similar) so that when I read the header later I will remember to fill in a missing paragraph, but it would be nice to have a warning generated so that when I build my library, I see all such similar warning in a single place.

The idea is that I'd do something like:

/**
 * Long introduction paragraph about a class.
 *
 * @todo explain super special awesome feature #31
 */
@interface MECoolThing : NSOjbect {
  // ...
}
// ...
@end

and the todo would show up as a warning.

[tomaz]

Sounds useful although only short term need - until the documentation is completed. Will mark it as feature request for pool of ideas.

[jk]

Perhaps it's better to scan for // TODO: since Xcode does the same.

[tomaz]

This is also an option, but it would require more processing - currently anything inside method declaration is ignored, only comment before method is used and processed.

[dented42]

I would prefer that appledoc not scan for // TODO:, because I use it in a context that is separate from how I would use @todo. For me at least, // TODO: is used to specify unfinished/ugly code that needs fixing, whereas I would use @todo in appledoc to indicate problems with documentation. I find the separation to be cleaner and perhaps a bit simpler, and the implementation would also be easier. But again, that's just my opinion.

[dirtyhenry]

I agree with dented42.