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.
