I would like to see the formal implementation of javadoc/phpdoc style commenting auto-complete in the IDE; right now one can add such comments, but I am not sure if there is a way to generate the documentation files - if you ran the code through the javadoc or phpdoc processor, I am not sure what it would do or generate (is there an avr-gccdoc?). I think with auto-complete (ie, enter "/**" and the entire block of blank comments are filled in, using the argument declarations, etc from the function declaration line) and a parser, this could form a useful and fairly standard way to document sketches.
I believe the AVR Freaks use Doxygen. Would that be an acceptable / better choice than Javadoc?
Well, I am most familiar with javadoc/phpdoc (they're similar) style comments (my day job is currently as a PHP web application developer), but if there is already a standard in use (I've heard of Doxygen) for AVR, then that would probably be the one to use; it just needs to be integrated into the IDE.
I just took a quick look at Doxygen, and it looks like it supports Javadoc style comments(and a whole host of other styles, plus a ton of other stuff, including having cross-platform support.
I would give it two thumbs up!
