[Openocd-development] doxygen update
Hi all, As a consequence of my recent clean-up work, I turned on some of the basic GraphViz features in doxygen. This feature can be turned off by change the HAVE_DOT Doxyfile setting from YES to NO. Its file dependency graphs are now much more insightful than before I started my clean-up, so I think they should be referenced by as many developers as possible. Further, I would like to improve the doxygen output until it provides a fairly complete API reference manual. Patches that move us toward that goal would be most welcome. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] doxygen update
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. Nico Coesel -Oorspronkelijk bericht- Van: openocd-development-boun...@lists.berlios.de [mailto:openocd-development-boun...@lists.berlios.de] Namens Zach Welch Verzonden: maandag 11 mei 2009 9:30 Aan: openocd-development Onderwerp: [Openocd-development] doxygen update Hi all, As a consequence of my recent clean-up work, I turned on some of the basic GraphViz features in doxygen. This feature can be turned off by change the HAVE_DOT Doxyfile setting from YES to NO. Its file dependency graphs are now much more insightful than before I started my clean-up, so I think they should be referenced by as many developers as possible. Further, I would like to improve the doxygen output until it provides a fairly complete API reference manual. Patches that move us toward that goal would be most welcome. Cheers, Zach ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
Re: [Openocd-development] doxygen update
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
Re: [Openocd-development] doxygen update
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? Allright! I need to write a driver somewhere in the next couple of weeks/months (when the JTAG programmer hardware arrives). Perhaps I can sketch/write some outlines on putting a driver together. I just don't know how this would work with the current version of OpenOCD. A lot seems to be happening lately (which is good!) but I'm not sure the current driver model is still the same as version 0.1.0. Nico Coesel ___ Openocd-development mailing list Openocd-development@lists.berlios.de https://lists.berlios.de/mailman/listinfo/openocd-development
