Dai­ly doxy­gen gen­er­at­ed docs of the FreeB­SD ker­nel (head)

I man­aged to get some time to set­up an auto­mat­ed gen­er­a­tion of the doxy­gen docs for ker­nel sub­sys­tems of FreeB­SD on my webserver.

Every night/morning (Ger­man time­zone) the sources will be updat­ed, and the docs get regen­er­at­ed (this takes some time). Cur­rent­ly this depends upon some patch­es to the make­file and doxy­gen con­fig files in tools/kerneldoc/subsys. Every­thing is gen­er­at­ed direct­ly in the place where the web­serv­er will look for to deliv­er the pages, so if you browse this in the mid­dle of the gen­er­a­tion, the con­tent may not be con­sis­tent (yet).

Please be nice to the web­serv­er and do not mir­ror this. You can gen­er­ate this your­self very easy. Assum­ing you have the FreeB­SD source on a local hard disk, you just need to down­load the patch from http://www.Leidinger.net/FreeBSD/current-patches/ (if you do not find dox.diff, update your FreeB­SD sources and every­thing will be OK), apply the patch, cd into tools/kerneldoc/subsys and run “make all” (or “make vm” or what­ev­er you are inter­est­ed in). You need doxy­gen installed, off course.

If you want to set­up some­thing like this your­self, just down­load the script which is doing all the work, change some vari­ables in the begin­ning, and cre­ate your own local ver­sion of the com­plete docs.

In case this is using sig­nif­i­cant traf­fic, I will ask core/admins if there is the pos­si­bil­i­ty to host it on FreeBSD.org resources.

A lit­tle bit of cleanup

I com­mit­ted a lit­tle bit of cleanup / some XXX com­ments to the soundsys­tem, extend­ed the linux(4) man page a lit­tle bit and removed some alpha spe­cif­ic sec­tion 4 man pages which where over­looked at the time alpha was removed from current.

I think I will enjoy the sun in the back­yard a lit­tle bit now… 😎

Bikesheds, FC4 and SoC

The last week has seen some bikesheds. One of them was my com­mit of the doxy­gen infra­struc­ture for the ker­nel sub­sys­tems. Some peo­ple don’t like the way doxy­gen requires some markup tags in the com­ments, some peo­ple don’t think such API docs pro­vide addi­tion­al val­ue and some peo­ple fear that 3rd par­ty devel­op­ers may use some func­tions which should­n’t be used. I don’t repeat the counter-arguments of myself and oth­er peo­ple here, but there are peo­ple out there which already make use of the cur­rent unsat­is­fac­to­ry doxy­gen out­put and are hap­py about this infra­struc­ture. Luck­i­ly is was super­seed­ed by anoth­er bikeshed (and gnn@ wants to work on doc­u­ment­ing a sub­sys­tem to show the ben­e­fits to those peo­ple which do not think yet, that this is a good idea). On a relat­ed issue, I’m wait­ing on a repo copy of src/sys/doc to src/tools (it’s one of two repo copies I’m wait­ing for, ncvs@ seems to be bussy ATM). Some doc@ peo­ple think it is more appro­pri­ate there.

The FC4 lin­ux base port and the xorg based lin­ux X11 libs port are sched­uled for test­ing in an exper­i­men­tal ports build run, we may see the switch of the default lin­ux base port in the not so dis­tant future. It seems Boris is work­ing on updates to the rest of the lin­ux­o­la­tor infra­struc­ture in the Ports Col­lec­tion (gtk, …), so we may see a lot of updates there after the switch of the default lin­ux base port.

In the last days I also helped/talked with my SoC stu­dents. Roman is play­ing a lit­tle bit with an amd64 tin­der­box he got access to and as a result he com­mit­ted sup­port for build­ing the lin­ux­o­la­tor on amd64 as a mod­ule to per­force (call for testers: he did send a patch to emulation@, please give it a try if you own an amd64 box). Ryan is cat­a­loging the IOCTL’s and their sta­tus (imple­ment­ed, obso­lete, …) in the FreeB­SD wiki. I already pri­or­ized those he did so far, and gave some sug­ges­tions how to pro­ceed with the impor­tant ones. This way he has­n’t to wait for me or Ariff when he is fin­ished with the cat­a­loging (being a men­tor liv­ing in a dif­fer­ent time zone means you should be ahead of your stu­dent… being ahead even before he is able to asks ques­tions is … a boost for your own ego 😉 ).

The ker­nel sub­sys­tem API doc­u­men­ta­tion gen­er­a­tion framework.

I com­mit­ted the ker­nel sub­sys­tem API doc­u­men­ta­tion gen­er­a­tion frame­work. It allows to gen­er­ate the API doc­u­men­ta­tion of a sub­sys­tem (with doxy­gen) just by adding a short con­fig file (around 22 lines with com­ments and blank lines, maybe 14 lines with­out com­ments and blank lines). Here’s an exam­ple of such a config:

—snip—
PROJECT_NAME = “FreeB­SD ker­nel sound device code”
OUTPUT_DIRECTORY = $(DOXYGEN_DEST_PATH)/dev_sound/
EXTRACT_ALL = YES # for undoc­u­ment­ed src, no warn­ings enabled
INPUT = $(DOXYGEN_SRC_PATH)/dev/sound/

GENERATE_TAGFILE = dev_sound/dev_sound.tag
TAGFILES = dev_pci/dev_pci.tag=../../dev_pci/html \
dev_usb/dev_usb.tag=../../dev_usb/html
@INCLUDE_PATH = $(DOXYGEN_INCLUDE_PATH)
@INCLUDE = common-Doxyfile
—snip—

The frame­work is con­fig­ured to not only gen­er­ate the HTML ver­sion, but also a PDF version.

Sub­sys­tems for which docs are gen­er­at­ed cur­rent­ly (con­figs for oth­er sub­sys­tems are welcome):

  • cam
  • cryp­to
  • dev_pci
  • dev_sound
  • dev_usb
  • geom
  • i4b
  • kern
  • libkern
  • lin­ux
  • net80211
  • net­graph
  • netinet
  • netinet6
  • netipsec
  • open­cryp­to
  • vm

Peo­ple which want to help doc­u­ment­ing the code may want to have a look at the spe­cial com­mands doxy­gen under­stands.