Documenting using code comments..
-
Yesterday there was a thread on commenting in the lounge. I wonder if anyone know of a good tool that converts source code and comments into some form of documentation? Like a better version of the MSDN sample API2Help or something like JavaDoc. How do you document your code? /moliate
-
Yesterday there was a thread on commenting in the lounge. I wonder if anyone know of a good tool that converts source code and comments into some form of documentation? Like a better version of the MSDN sample API2Help or something like JavaDoc. How do you document your code? /moliate
http://www.stack.nl/~dimitri/doxygen/ /ravi "There is always one more bug..." ravib@ravib.com http://www.ravib.com
-
Yesterday there was a thread on commenting in the lounge. I wonder if anyone know of a good tool that converts source code and comments into some form of documentation? Like a better version of the MSDN sample API2Help or something like JavaDoc. How do you document your code? /moliate
There is no such tool. No such tool is possible. Commenting code and documenting code are two different things. Comments are used to describe interface and inner workings. Documentation is meant to describe interface and usage. Yes, there is overlap, but the fundamental differences between the two mean that trying to use one to do both jobs is a futile effort. I've arrived at this opinion after trying to use documentation that was generated this way. In all cases the quality of the documentation is miserable, on the order of: CWhatsIt::SetFooBar void CWhatsIt::SetFoobar() Arguments: none Return Value: none Sets the FooBar property. And of course, the comments are now unreadable because they have all sorts of formatting codes inserted in them. Documentation takes effort. Attempting to shortcut the process by using an automated docs generator is not a solution. As far as code docs go.. I try to include detailed comments for thisngs like class usage, function purpose, etc, in the headers. Then, when the code is stable, I write an overview of the classes for inclusion in a separate document, with pointers to the header files.
-
There is no such tool. No such tool is possible. Commenting code and documenting code are two different things. Comments are used to describe interface and inner workings. Documentation is meant to describe interface and usage. Yes, there is overlap, but the fundamental differences between the two mean that trying to use one to do both jobs is a futile effort. I've arrived at this opinion after trying to use documentation that was generated this way. In all cases the quality of the documentation is miserable, on the order of: CWhatsIt::SetFooBar void CWhatsIt::SetFoobar() Arguments: none Return Value: none Sets the FooBar property. And of course, the comments are now unreadable because they have all sorts of formatting codes inserted in them. Documentation takes effort. Attempting to shortcut the process by using an automated docs generator is not a solution. As far as code docs go.. I try to include detailed comments for thisngs like class usage, function purpose, etc, in the headers. Then, when the code is stable, I write an overview of the classes for inclusion in a separate document, with pointers to the header files.
Jim A. Johnson wrote: Documentation takes effort. Attempting to shortcut the process by using an automated docs generator is not a solution Documentation tools are not shortcuts to writing good comments. Instead, they allow you to generate publishable and searchable documentation from source code containing properly tagged content. Sun's entire Java documentation is generated using JavaDoc. For an example of the output, see: http://java.sun.com/j2se/1.4/docs/api/index.html At my previous job, the nightly build flagged JavaDoc errors that would help identify classes that were not fully documented. Code reviews caught sloppy comments. /ravi "There is always one more bug..." ravib@ravib.com http://www.ravib.com
-
Yesterday there was a thread on commenting in the lounge. I wonder if anyone know of a good tool that converts source code and comments into some form of documentation? Like a better version of the MSDN sample API2Help or something like JavaDoc. How do you document your code? /moliate
I use Cocoon
-
Yesterday there was a thread on commenting in the lounge. I wonder if anyone know of a good tool that converts source code and comments into some form of documentation? Like a better version of the MSDN sample API2Help or something like JavaDoc. How do you document your code? /moliate
I use doxygen all the time and it has great features for customizing the output that the tool generates. What's also cool is that it can create a HTML Help project and index for you which is a great time saver. It does a great job of cross referencing the code and creating an easy to use, searchable set of HTML pages, plus it can spit out RTF or LaTex if you prefer
-
There is no such tool. No such tool is possible. Commenting code and documenting code are two different things. Comments are used to describe interface and inner workings. Documentation is meant to describe interface and usage. Yes, there is overlap, but the fundamental differences between the two mean that trying to use one to do both jobs is a futile effort. I've arrived at this opinion after trying to use documentation that was generated this way. In all cases the quality of the documentation is miserable, on the order of: CWhatsIt::SetFooBar void CWhatsIt::SetFoobar() Arguments: none Return Value: none Sets the FooBar property. And of course, the comments are now unreadable because they have all sorts of formatting codes inserted in them. Documentation takes effort. Attempting to shortcut the process by using an automated docs generator is not a solution. As far as code docs go.. I try to include detailed comments for thisngs like class usage, function purpose, etc, in the headers. Then, when the code is stable, I write an overview of the classes for inclusion in a separate document, with pointers to the header files.
Jim A. Johnson wrote: There is no such tool. No such tool is possible. [...] I've arrived at this opinion after trying to use documentation that was generated this way. "I had a Ford Pinto once, and they recalled it. Therefore all cars are crap." :-) The example you gave is just plain old poor documentation, which you can (surprise!) generate manually as well as automatically. Most decent generators will generate nothing for void returns or parameters. What did you want to see in the documentation for the SetFoobar() method? That could have been included painlessly in the class header, and picked up by a generator. The real benefit to automatic documentation is that you have single source for all the code-level documentation--both the docs that you see in the headers and the descriptions that go in the design document. The design docs will not drift from the code comments, as often happens, because they can't. In database terms, you're normalizing the database. I agree that you can't use this documentation in a vacuum. You still need a design document that tells you higher-level things, and I'll agree that this document can't be automatically generated. Tim Lesher http://www.lesher.ws
-
Jim A. Johnson wrote: There is no such tool. No such tool is possible. [...] I've arrived at this opinion after trying to use documentation that was generated this way. "I had a Ford Pinto once, and they recalled it. Therefore all cars are crap." :-) The example you gave is just plain old poor documentation, which you can (surprise!) generate manually as well as automatically. Most decent generators will generate nothing for void returns or parameters. What did you want to see in the documentation for the SetFoobar() method? That could have been included painlessly in the class header, and picked up by a generator. The real benefit to automatic documentation is that you have single source for all the code-level documentation--both the docs that you see in the headers and the descriptions that go in the design document. The design docs will not drift from the code comments, as often happens, because they can't. In database terms, you're normalizing the database. I agree that you can't use this documentation in a vacuum. You still need a design document that tells you higher-level things, and I'll agree that this document can't be automatically generated. Tim Lesher http://www.lesher.ws
What you say makes some sense. But I'd need to see some examples of good generated docs before I can agree in total. The JavaDocs example looked good. The Cocoon samples were more of what I've seen in the past. I would like to see how mangled and unreadable the code that generated these comments is now (AutoDuck's formatting requirements made hash of the source comments). Perhaps I should give this another whirl.
-
What you say makes some sense. But I'd need to see some examples of good generated docs before I can agree in total. The JavaDocs example looked good. The Cocoon samples were more of what I've seen in the past. I would like to see how mangled and unreadable the code that generated these comments is now (AutoDuck's formatting requirements made hash of the source comments). Perhaps I should give this another whirl.
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