On Mon, 2009-05-11 at 10:08 +0200, Nico Coesel wrote: > Zach, > I'm a little concerned here. I've seen many doxygen generated API > 'reference' manuals. Most of them are useless because they don't > describe why a certain function is there and what its relation is to > other functions. Doxygen is a fine tool to get a list of functions and > their parameters but the same information can be obtained by importing > the source into an IDE like Eclipse or Visual Studio. I have been > digging around in other peoples software a lot. The biggest question is > always: how does the data flow through the software and why is it > structured the way it is. Unfortunately, most doxygen generated > documents don't contain this information. > > A diagram which shows the logical blocks / layers of the software and > some text on how they interact is very very useful.
I agree that there are different levels to the documentation, and I think that doxygen does a great job for API reference. It can also provides function call graphs, which begins to provide some of the code-flow insight that you describe. However, you are right in saying that we need additional documentation that describes the architecture at higher levels. Such text and figures could also be integrated into the doxygen manual, allowing the texinfo document to focus on high-level usage and TCL script documentation. How does that plan sound? Cheers, Zach _______________________________________________ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
