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

[Alexander Leidinger]

Quoting gnn at freebsd.org (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 sheet 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