From owner-freebsd-questions@FreeBSD.ORG Fri Dec 30 03:43:17 2011 Return-Path: Delivered-To: freebsd-questions@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id BC71E106566C for ; Fri, 30 Dec 2011 03:43:17 +0000 (UTC) (envelope-from djackson452@gmail.com) Received: from mail-ey0-f182.google.com (mail-ey0-f182.google.com [209.85.215.182]) by mx1.freebsd.org (Postfix) with ESMTP id 55E6A8FC0C for ; Fri, 30 Dec 2011 03:43:16 +0000 (UTC) Received: by eaaf13 with SMTP id f13so17529031eaa.13 for ; Thu, 29 Dec 2011 19:43:16 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=gamma; h=mime-version:date:message-id:subject:from:to:content-type; bh=ksq2G1XgpPJZ4MceqQUFYGS3tYzzlr4NtKAMQSUVjNY=; b=ZRLivyGF1cxCyq3my9RuS/xQ6Zol3a8WCtMmp2D1n2J/IpsZ+adJrSdYwUd2CV+fWF JQmgGXt9O1K84ZsxOtQiTvWmOuNcTUF6yf3lYYhu4x3adDAfScKfm/RKAxH0CojiQgim LM7uquvxTY6PdNZRBgZoAaCpkDCXD1XDQsWwQ= MIME-Version: 1.0 Received: by 10.204.133.212 with SMTP id g20mr9294940bkt.82.1325216596205; Thu, 29 Dec 2011 19:43:16 -0800 (PST) Received: by 10.204.130.27 with HTTP; Thu, 29 Dec 2011 19:43:16 -0800 (PST) Date: Thu, 29 Dec 2011 22:43:16 -0500 Message-ID: From: David Jackson To: freebsd-questions@freebsd.org Content-Type: text/plain; charset=ISO-8859-1 X-Content-Filtered-By: Mailman/MimeDel 2.1.5 Subject: FreeBSD Kernel Internals Documentation X-BeenThere: freebsd-questions@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: User questions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 30 Dec 2011 03:43:17 -0000 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