So I Was Thinking...
Author
When I'm working on a personal project, often times I find myself opening up the source files of code I've written weeks ago and searching through it to find out what functions I've defined, what their parameters are, and what they return. Now, the thought of sifting through the old code often leaves me feeling unmotivated to get to work on my project.
So I was thinking, is it a reasonable idea to write my own sort of documentation in a text file to outline the functions in each class? Does anyone practice this? Please share your opinions on this.
Why write your own documentation if programs like doxygen do it automatically out of your code and your comments?
Edit: And since several of your other threads are specifically about Java, javadoc does the same for Java and comes straight with the JDK.
Edit: And since several of your other threads are specifically about Java, javadoc does the same for Java and comes straight with the JDK.
Author
Thank you very much. This pretty much sums up any discussion that could have resulted from this thread I guess, haha.
Quote:
Why write your own documentation if programs like doxygen do it automatically out of your code and your comments?
Because while a documentation of all the functions, classes and interfaces is useful, it doesn't tell the end user anything about how to use your codebase.
Do NOT forget to document how all the code ties together. You can browse the doxygen of something like Bullet Physics all day and it wouldn't get you closer to understanding what to do. But look at the samples and documentation and you can get started very quickly.
The OP asked for help about how to write documentation for himself, not for some largish library he intends to publish.
doxygen isn't restricted to document classes, enumeration, functions, namespaces, ... It also provides support for the todo list, example code (inclusively links into the member documentation), and logical grouping. And the \page, \section, \subsection stuff allows to incorporate plenty of explanatory pages smoothly.
Quote:Original post by X Abstract X
often times I find myself opening up the source files of code I've written weeks ago and searching through it to find out what functions I've defined
Generally, you should try to design your code so that you DON'T need to look into the internals of classes to know how to use them, but maybe that wasn't the issue. :)
As for simply enumerating the public parts, that's best left to your IDE (or if that's not available), a Documentation generator. It's so much easier to browse through HTML documentation than reading through multiple .hpp or .java files.
I mostly write direct in-source documentation only for classes, methods and constants, if more explanation than that is needed that should probably be put in some code design doc in first place.
This topic is closed to new replies.
Advertisement
Popular Topics
Advertisement
