FreeBSD Kernel Internals Documentation

[David Jackson]

I have had an interest in studying the FreeBSD kernel and getting to know
its internals better. After all, in Open source projects, they say,
community contributions are important.

However, My finding is that due to poor documentation, the FreeBSD kernel
is nearly impenetrable to an outsider. I have been able to find no
comprehensive documentation of kernel internals. I have found it nearly
impossible, due to lack of comprehensive documentation, much of any of the
kernel internals. What I see is an internal cliche of developers who are
aware of its myraid of undocumented esoteric secrets, and very little to
actually help anyone else to understand it.

Any good, well designed software projects will have comprehensive
documentation of the source code, this includes code comments, information
on what every piece of code does, how the entire system fits together, and
descriptions of every variable and function. Any well run project would
insist that code contributors upload full and comprehensive documentation
of how their source code is written, how it works, etc.

Documentation is vital and good practice because it saves time, it prevents
people new to the project having to waste immense amounts of time trying to
figure out a vast and cryptic puzzle. Without good documentation software
can be nearly useless, unmaintainable and difficult for an outsider to
learn, to the point where it may actually take less time to just throw it
out and start from scratch.

These are reasons that FreeBSD needs better documentation, documentation of
how the entire system fits together, what lines of code do, the purpose of
variables and functions, etc, in descriptive English. This is key to
developing maintainable software.

I saw where someone automatically generated "documentation" with Doxygen.
This is nearly useless, because all it shows is a huge list of functions
and variables but does not include any text on what they do. At best,
Doxygen can only provide a template for documentation that can be filled in
with descriptive English information on what everything does.

One idea might be to have an official wiki that contains the template
generated by Doxygen which can then be filled in. When changes to the
source code is made, it is good practice for the commiter of such changes
to document their code as it is submitted.

This allows others who come along who need to maintain the code to more
easily understand what the code does.

Another idea which would also improve the useability of FreeBSD would be to
have a wiki which would be updated by kernel contributors whenever they add
support for a certain piece of hardware. This would make finding hardware
compatability information easier from one central, up to date and current
source of information.

These documentaiton ideas, for commiters to document their code when they
upload it, and document their hardware support additions, are just good
software practices that should be highly recommended and encouraged