Date: Thu, 29 Dec 2011 22:43:16 -0500 From: David Jackson <djackson452@gmail.com> To: freebsd-questions@freebsd.org Subject: FreeBSD Kernel Internals Documentation Message-ID: <CAGy-%2Bi-NN_SOYrrE6WgHyCBa5VzFexwT_C9UYhO3GyjvfsxpAA@mail.gmail.com>
next in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CAGy-%2Bi-NN_SOYrrE6WgHyCBa5VzFexwT_C9UYhO3GyjvfsxpAA>