Date: Mon, 22 May 2006 16:50:11 -0700 From: gnn@freebsd.org To: Alexander Leidinger <Alexander@Leidinger.net> Cc: Poul-Henning Kamp <phk@phk.freebsd.dk>, hellmuth.michaelis@t-online.de, Julian Elischer <julian@elischer.org>, freebsd-arch@freebsd.org Subject: 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 ...) Message-ID: <m2bqtpk4b0.wl%gnn@neville-neil.com> In-Reply-To: <20060522101825.adfzv59y1eogwocs@netchild.homeip.net> References: <200605181516.15541.hm@kts.org> <39318.1147960050@critter.freebsd.dk> <m2ejyrl0gd.wl%gnn@neville-neil.com> <20060519143116.9iuvd81es0g0owkc@netchild.homeip.net> <m2fyj3f3re.wl%gnn@neville-neil.com> <20060522101825.adfzv59y1eogwocs@netchild.homeip.net>
next in thread | previous in thread | raw e-mail | index | archive | help
At Mon, 22 May 2006 10:18:25 +0200, Alexander Leidinger wrote: > > Quoting gnn@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@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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?m2bqtpk4b0.wl%gnn>