doxygen target (was: Re: cvs commit: src Makefile.inc1 ObsoleteFiles.inc src/etc/defaults rc.conf src/etc/mtree BSD.usr.dist src/etc/rc.d Makefile isdnd pcvt syscons src/release/picobsd/build picobsd src/share/man/man4 Makefile atkbd.4 kbdmux.4 pcvt.4 splash.4 vkbd.4 ...)

[gnn at freebsd.org]

At Mon, 22 May 2006 10:18:25 +0200,
Alexander Leidinger wrote:
> 
> Quoting gnn at neville-neil.com (from Sun, 21 May 2006 14:48:37 -0700):
> 
> > At Fri, 19 May 2006 14:31:16 +0200,
> > Alexander Leidinger wrote:
> >>
> >> Quoting "George V. Neville-Neil" <gnn at neville-neil.com> (from Thu, 18
> >> May 2006 10:14:26 -0700):
> >>
> >> > I so hate to chime in on this thread, but I really think we need to
> >> > start putting things into the code and using Doxygen, or a moral
> >> > equivalent, to at least have a chance of keeping such things up to
> >> > date.  Someone a while back set up a proper Doxygen file for use with
> >> > FreeBSD and we might simply pursue that tack.
> >>
> >> http://www.leidinger.net/FreeBSD/src_docs/
> >> http://www.leidinger.net/FreeBSD/FreeBSD-Dox.tar.bz2
> >>
> >> Feel free to send/suggest further subsystems/improvements.
> >
> > The one thing I'd like to suggest is that this be made part of the
> > tree with an optional make target.  How should we go about doing that?
> 
> We already have a doxygen config file in the tree, it covers the  
> entire kernel. But I think my approach of generating docs for  
> subsystems instead of the entire kernel may be more easy to understand  
> for people which want to understand a part of the kernel.
> 

BTW I have move this to arch@ since I think it makes more sense there.

> Regarding the make target, do you think about "cd /usr/src; make  
> doxygen" or about "cd /usr/src/<mumble>; make doxygen"?

Yes :-)  It hsould be possible to be as specific or non-specific as
possible.  There can then be nightly builds of the docs, much like
running global nightly to get cross references like I put up on
codespelunking.org

> The targets in the .tar.bz2 generate a HTML version too. Currently
> the HTML version is around 300 MB, and it only covers a small part
> of the kernel. Shall the HTML version also be generated (not
> available online)? What about the destination, where do you want the
> HTML version and/or the PDF version (needs pdflatex as a build tool)
> to be placed (I can't come up with a good destination)? The HTML
> version is generated by doxygen directly, the PDF needs to be
> generated from the latex version, so in case of the PDF version it
> would make sense to have a "doxygen" and "doxygeninstall" target,
> but not for the HTML version (except you want to generate everything
> in OBJDIR and then do a copy to the destination).
> 
> Yes, I'm asking bikeshed questions... but only because I can't think  
> of a good answer myself ATM.

My preference, and I'm not a Doxygen guru, is that we generate HTML
from /usr/src into a /usr/doc directory, which is like /usr/obj, then
some folks can serve /usr/doc on the net.  Sub directory builds should
make sub-directory doc directories.  I.e. /usr/src/sys/netinet/doc.  I
think that /usr/src/sys is already a special root which gets a doc
directory, and I think that's fine.  For now I want to emphasize
simplicity.

THe other thing we need guidance on is, if people want to, how to most
easily add clear annotations to soiurce that make Doxygen happy.  A
one page cheat sheet would go a long way towards making this usable by
people who don't like to write documentation :-)

Thanks,
George