On Tue, Apr 07, 2009 at 10:47:07PM +0100, Robin Cornelius wrote: > What is not clear from [2] & [3] is that doxygen also supports a simple > comment/mark up system for documenting the code. What this means is > comments can be added explaining API functions and interfaces through > out the code and this will be used when generating the html pages to > provide more thorough documentation, with clickable links directly to > the code and class references.
Let me add that (the use of) doxygen in itself is not very useful. What makes the end-product (the documentation) useful is extensive documentation by the coders, not just having (for example) a class hierarchy. So, why doxygen? One of the strong points of doxygen (over, for example documentation on a wiki) is that the documentation and the code are kept very close together. This motivates coders a lot more to keep the documentation up to date: when code is changed, the documentation is updated and changed as well, in the same file. This makes it also easier to make it part of the review of patches to demand that documentation is kept up to date. I hate to do this (cause it's of course my own project ;), but here is an example of how documentation can look like: http://www.xs4all.nl/~carlo17/cwchessboard/index.html If you click around, you will note that only the somewhat larger blocks of text really tell you something, not the one-liners. However, if a developer would really dig deep into this project, one of the strong points (of using doxygen) is that this documentation is almost fully automated hyperlinked! While reading about what class does what in a summary, you can click directly through to that class for a quick overview. -- Carlo Wood <[email protected]> _______________________________________________ Policies and (un)subscribe information available here: http://wiki.secondlife.com/wiki/SLDev Please read the policies before posting to keep unmoderated posting privileges
