I tried AutoDuck a few years ago, and immediately abandoned it for the reason you mentioned. One of my current jobs is finding a way to do autodocumentation without screwing up the original source too much. I've settle on Doxygen because that's the most flexible documentor that I've found, and that lets me streamline the comments quite a bit while still getting some good features from it. Here's an example:
/** Reverse a string in-place. Reverses the string
* character-by-character, working from both ends toward the middle.
* @bug This function doesn't handle MBCS characters.
*/
void reverse(char * str ///< String to reverse
)
{
[...]
}
This is a trivial example, of course, but you can see that the markup isn't too onerous if you set up the Doxygen settings right. As closely as CodeProject will let me render it, this yields:
reverse.c
Functions
void reverse (char *str) Reverse a string in-place. More...
Function Documentation
void reverse ( char * str ) Reverse a string in-place. Reverses the string character-by-character, working from both ends toward the middle. Bug: This function doesn't handle MBCS characters. Parameters: str String to reverse The hyperlink at "More..." jumps to the longer Function Documentation entry for the function (useful if you have a module with many functions), and the "Bug" hyperlink jumps to a separate page with a master list of bug entries, with file names and line numbers. Tim Lesher http://www.lesher.ws
