Date: Sat, 5 Feb 2005 22:29:45 -0800 (PST) From: "ALeine" <aleine@austrosearch.net> To: justin@shiningsilence.com Cc: kernel@crater.dragonflybsd.org Subject: Re: RFC: backporting GEOM to the 4.x branch Message-ID: <200502060629.j166Tj8c027144@marlena.vvi.at>
next in thread | raw e-mail | index | archive | help
justin@shiningsilence.com wrote: > The subject of doxygen has come up a few times, and people haven't been > too keen on it: > > http://leaf.dragonflybsd.org/mailarchive/kernel/2003-10/msg00197.html > http://leaf.dragonflybsd.org/mailarchive/kernel/2003-10/msg00199.html > > I'm assuming you'd have to have the extra data from doxygen to generate > those graphs, as I've not done that process, myself. Basically, doxygen generates graph file language (dot) files, which are then fed to graphviz to generate the graphs. An important thing to note is that the HTML generated by doxygen uses map area tags, which means that graph nodes are clickable, so you can browse code graphically and very quickly familiarize yourself with all the dependencies and intricate details. Here is another demonstrative example: http://manson.vistech.net/~manager/vfs__syscalls_8c_a44_cgraph.png If you install doxygen from the FreeBSD ports (devel/doxygen) it will automatically install graphviz (graphics/graphviz) and then you can just launch doxywizard and create a doxyfile within 3 minutes even if you've never set eyes on doxygen before. Once you are happy with the results all you need is a cron job to run doxygen using your doxywizard generated doxyfile. There is no maintenance overhead, so I do not see a reason why this should not be implemented. Also, the generated documentation can reside where ever you want it to be, so the source tree can remain intact. This sort of documentation should be seen as supplementary and not as a replacement for the handbook documentation or anything else. It's also not meant to be implemented in a way that would interfere with the established source coding and documenting practices. The few developers who "live the code" could totally ignore the doxygen generated documentation, but the rest of us would find it a great help to have this kind of resource. I also think that even those hardcore developers could use this kind of documentation for quickly looking up all the functions that call a certain function and to save time when explaining the details to other developers. Why spend 5 minutes describing something you can explain by having someone take a look at a graph? Maybe most developers think that etags and cscope are all they need, but to me personally the reference graphs alone are reason enough to use doxygen. As you probably know Robert Watson runs a nice FreeBSD Cross-reference site (fxr.watson.org), but I believe doxygen to be superior to the LXR/FXR engine, so perhaps it would be a good idea to replace LXR/FXR with doxygen. Any opinions on that? The bottom line is, doxygen takes 10 minutes to set up and other than a fair amount of CPU time and a few GB of disk space for the generated documentation it requires nothing special. :-) It will not interfere with anyone's work, but it will make the development process easier and more accessible to a number of potential developers. ALeine ___________________________________________________________________ WebMail FREE http://mail.austrosearch.net
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200502060629.j166Tj8c027144>