Re: 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 ...)

Quoting gnn@xxxxxxxxxxx (from Mon, 22 May 2006 16:50:11 -0700):

At Mon, 22 May 2006 10:18:25 +0200,
Alexander Leidinger wrote:

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

I try to come up with the /usr/src doxygen target first.

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

Sounds fine to me. One directory per subsystem if we go the split-up way.

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.

I'm not sure the subdirectory builds are that simple to implement in a generic fashion (I have to play around with some ideas here...). Adding a target by hand to each interesting subdirectory is easy.

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 *** would go a long way towards making this usable by
people who don't like to write documentation :-)

I think http://www.stack.nl/~dimitri/doxygen/docblocks.html provides a good start (until someone writes doxygen_style(9) :-) ).

A FAQ is available at http://www.stack.nl/~dimitri/doxygen/faq.html and http://www.stack.nl/~dimitri/doxygen/commands.html contains a list of all doxygen recognized documentation-commands.

Bye,
Alexander.

--
Selling GoodYear Eagle F1 235/40ZR18, 2x 4mm + 2x 5mm, ~150 EUR
you have to pick it up between Germany/Saarland and Luxembourg/Capellen
http://www.Leidinger.net Alexander @ Leidinger.net: PGP ID = B0063FE7
http://www.FreeBSD.org netchild @ FreeBSD.org : PGP ID = 72077137

_______________________________________________
freebsd-arch@xxxxxxxxxxx mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-arch
To unsubscribe, send any mail to "freebsd-arch-unsubscribe@xxxxxxxxxxx"