I managed to get some time to setup an automated generation of the doxygen docs for kernel subsystems of FreeBSD on my webserver.
Every night/morning (German timezone) the sources will be updated, and the docs get regenerated (this takes some time). Currently this depends upon some patches to the makefile and doxygen config files in tools/kerneldoc/subsys. Everything is generated directly in the place where the webserver will look for to deliver the pages, so if you browse this in the middle of the generation, the content may not be consistent (yet).
Please be nice to the webserver and do not mirror this. You can generate this yourself very easy. Assuming you have the FreeBSD source on a local hard disk, you just need to download the patch from http://www.Leidinger.net/FreeBSD/current-patches/ (if you do not find dox.diff, update your FreeBSD sources and everything will be OK), apply the patch, cd into tools/kerneldoc/subsys and run “make all” (or “make vm” or whatever you are interested in). You need doxygen installed, off course.
If you want to setup something like this yourself, just download the script which is doing all the work, change some variables in the beginning, and create your own local version of the complete docs.
In case this is using significant traffic, I will ask core/admins if there is the possibility to host it on FreeBSD.org resources.
I committed a little bit of cleanup / some XXX comments to the soundsystem, extended the linux(4) man page a little bit and removed some alpha specific section 4 man pages which where overlooked at the time alpha was removed from current.
I think I will enjoy the sun in the backyard a little bit now… 😎
The last week has seen some bikesheds. One of them was my commit of the doxygen infrastructure for the kernel subsystems. Some people don’t like the way doxygen requires some markup tags in the comments, some people don’t think such API docs provide additional value and some people fear that 3rd party developers may use some functions which shouldn’t be used. I don’t repeat the counter-arguments of myself and other people here, but there are people out there which already make use of the current unsatisfactory doxygen output and are happy about this infrastructure. Luckily is was superseeded by another bikeshed (and gnn@ wants to work on documenting a subsystem to show the benefits to those people which do not think yet, that this is a good idea). On a related issue, I’m waiting on a repo copy of src/sys/doc to src/tools (it’s one of two repo copies I’m waiting for, ncvs@ seems to be bussy ATM). Some doc@ people think it is more appropriate there.
The FC4 linux base port and the xorg based linux X11 libs port are scheduled for testing in an experimental ports build run, we may see the switch of the default linux base port in the not so distant future. It seems Boris is working on updates to the rest of the linuxolator infrastructure in the Ports Collection (gtk, …), so we may see a lot of updates there after the switch of the default linux base port.
In the last days I also helped/talked with my SoC students. Roman is playing a little bit with an amd64 tinderbox he got access to and as a result he committed support for building the linuxolator on amd64 as a module to perforce (call for testers: he did send a patch to emulation@, please give it a try if you own an amd64 box). Ryan is cataloging the IOCTL’s and their status (implemented, obsolete, …) in the FreeBSD wiki. I already priorized those he did so far, and gave some suggestions how to proceed with the important ones. This way he hasn’t to wait for me or Ariff when he is finished with the cataloging (being a mentor living in a different time zone means you should be ahead of your student… being ahead even before he is able to asks questions is … a boost for your own ego 😉 ).
I committed the kernel subsystem API documentation generation framework. It allows to generate the API documentation of a subsystem (with doxygen) just by adding a short config file (around 22 lines with comments and blank lines, maybe 14 lines without comments and blank lines). Here’s an example of such a config:
PROJECT_NAME = “FreeBSD kernel sound device code”
OUTPUT_DIRECTORY = $(DOXYGEN_DEST_PATH)/dev_sound/
EXTRACT_ALL = YES # for undocumented src, no warnings enabled
INPUT = $(DOXYGEN_SRC_PATH)/dev/sound/
GENERATE_TAGFILE = dev_sound/dev_sound.tag
TAGFILES = dev_pci/dev_pci.tag=../../dev_pci/html \
@INCLUDE_PATH = $(DOXYGEN_INCLUDE_PATH)
@INCLUDE = common-Doxyfile
The framework is configured to not only generate the HTML version, but also a PDF version.
Subsystems for which docs are generated currently (configs for other subsystems are welcome):
People which want to help documenting the code may want to have a look at the special commands doxygen understands.