Re: GSoC proposal: NetBSD Kernel Documentation Management Toolchain

[Jukka Ruohonen <jruohonen%iki.fi@localhost>]

On Tue, Apr 05, 2011 at 07:04:55PM +0300, Vladimir Kirillov wrote:
> The purpose of my project is to define a generic approach to simplify
> the kernel code management tasks by defining a *unified* component
> model of NetBSD kernel programming interfaces using XML representation.

First of all, I think this is quite interesting project. You also clearly
know what you are doing, so this is worth pursuing even only as a research
project.

> - code references are not always complete and synchronized immediately
>   with manual pages
> - function signatures may be outdated
> - intro(9)-like pages may be left without attention (pages which mostly
>   contain references to other)
> - no documentation coverage control

I can see benefits for keeping things like sysctl(7), pci(4), or options(4)
up to date. But generally I have to agree with der Mouse. I do not think
that the problems in documentation are solvable by "automatic documentation
generators". Particularly the kernel is something where a human is almost
always required for good documentaton; the problem is not the code references
nor the function prototypes but more the insights, idioms, good practices,
assumptions not seen directly from the code -- the "why" -question. The
coverage is also a matter of opinion; not everything is worth documenting
nor is it even desirable to document everything.

I would hate to see our very decent man-page heritage turn into a Javadoc
style documentaton. Nor would I like to see @params in the actual code.
But, for instance, as a supplementary WWW documentation, that sounds great.
Especially neat would be "class diagrams" or Doxygen-like "call graphs".

>       * use clang to extract type information from code AST

Does clang and the associated utilities work on all supported architectures?

> - Define an XML specification (schema) for kernel API
>
> - Use the specification to create a header generation tool (using amd64
>   as a reference architecture) and a documentation generation/verification
>   tool with the following features:

I think goals like this should attain a throughout community discussion.
Personally I strongly dislike the use of XML, particularly when it is used
wrongly as a data storage model.

- Jukka.