Advices on code commenting

Started by
1 comment, last by GameDev.net 17 years, 6 months ago
Hello, In my engine I need to add documentation, in the form of code comments, to all my header files (hundreds of...) The documentation for each function includes a brief description of its usage and of its parameters and return values. Not only functions but other objects like classes have to be commented. Now, since this is a HUGE work to do, before starting I would appreciate the advice of people here on a suggested format. The possibility of automatically extracting a documentation file from the code by parsing the comments is a big bonus.I know .NET promotes in-code documentation in XML format, but I'm also aware of other formats (like the Doxygen one). Any advices on this matter? Thanks a lot, Stefano
Stefano LanzaTyphoon Engine
Advertisement
I've always liked the Javadoc format. It's parseable by Doxygen, Javadoc, and probably other tools as well.
My actual advice: choose a tool you like for documentation extraction, THEN choose a format you like and your tool supports.
I comment my code with http://www.naturaldocs.org/

This topic is closed to new replies.

Advertisement