Re: RFC: backporting GEOM to the 4.x branch

["ALeine" <aleine@xxxxxxxxxxxxxxxx>]

justin@xxxxxxxxxxxxxxxxxx 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