Earlier this month, Alexander Leidinger unveiled a set of FreeBSD kernel source documentation generated with the help of Doxygen. The Doxygen documentation system extracts code structure from source files producing file/directory indexes, struct reference and function descriptions, include dependency graphs, function call graphs, and other useful information. While the output is not entirely perfect, this can be a very helpful visual aid to browsing through source code. Among other notable FreeBSD subsystems, Alexander has generated html linked PDF documentation for GEOM, crypto, virtual memory, netgraph, crypto, cam and net80211. Read on for the original announcement and additional comments from Poul-Henning Kamp.

From: Alexander Leidinger [email blocked]
To: freebsd-current
Subject: Doxygen generated PDF's of parts of the kernel available
Date: 2005-05-01 15:08:00

Hi,

I've generated the doxygen docs for some parts of the kernel, in
particular for:
 - cam
 - crypto
 - dev/pci
 - dev/sound
 - dev/usb
 - geom
 - i4b
 - kern
 - libkern
 - net80211
 - netgraph
 - netinet
 - netinet6
 - netipsec
 - opencrypto
 - vm

Since the content of all html trees sums up to >360 MB, I'm just
uploading (it will need some minutes) the PDF's to
http://www.leidinger.net/FreeBSD/src_docs/

They describe -current as of today (and may contain some local
patches, I've used my development tree...).

Bye,
Alexander.




From: Poul-Henning Kamp [email blocked]
Subject: Re: Doxygen generated PDF's of parts of the kernel available
Date: 2005-05-01 15:59:52

In message <20050501170800.1bf7e377@Magellan.Leidinger.net>, Alexander Leidinge
r writes:

As far as I can tell, this gives us very little over a normal
code reading because we have not marked up our source code.

If we mark up the source code for doxygen, does that buy us anything
besides more text in the pdf files ?

Or to put the question another way:  Is the doxygen markup
*semantically* useful for any automated code-munching tools ?

Will anything tell us "you have an inconsistency here" or "this is
ambiguous" etc ?

It's not that I am against marking up for doxygen, that is probably
a good idea at some level.

My primary interest is tools which will tell us something about our
source code which we didn't know before, not just pretty-print what
we told it ourselves.

Poul-Henning


From: Alexander Leidinger [email blocked]
Subject: Re: Doxygen generated PDF's of parts of the kernel available
Date: 2005-05-01 16:22:01

On Sun, 01 May 2005 17:59:52 +0200 "Poul-Henning Kamp" wrote:

> As far as I can tell, this gives us very little over a normal
> code reading because we have not marked up our source code.

Yes.

> If we mark up the source code for doxygen, does that buy us anything

> besides more text in the pdf files ?

The answer depends upon what you think about a good API (or better: KPI,
Kernel Programming Interface) documentation.

> Or to put the question another way:  Is the doxygen markup
> *semantically* useful for any automated code-munching tools ?

I don't know such a tool.

> Will anything tell us "you have an inconsistency here" or "this is
> ambiguous" etc ?

Doxygen can tell us: "this isn't documented" or "the dependency/call
graph looks like ".

> It's not that I am against marking up for doxygen, that is probably
> a good idea at some level.

It integrates the documentation with the source. It's detectable if you
change the number of parameters but forget to document it. It allows to
follow inter-file code flow faster than just by using less or something
like this.

> My primary interest is tools which will tell us something about our
> source code which we didn't know before, not just pretty-print what
> we told it ourselves.

If you have tools or an IDE which tells you what the dependency/call
graph looks like, doxygen most likely doesn't fits your needs.

Bye,
Alexander.

• Archive of the Above Thread