From owner-cvs-src@FreeBSD.ORG Sun May 28 19:14:19 2006 Return-Path: X-Original-To: cvs-src@freebsd.org Delivered-To: cvs-src@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 947FA16AA82; Sun, 28 May 2006 19:14:19 +0000 (UTC) (envelope-from imp@bsdimp.com) Received: from harmony.bsdimp.com (vc4-2-0-87.dsl.netrack.net [199.45.160.85]) by mx1.FreeBSD.org (Postfix) with ESMTP id 9E0B543D5E; Sun, 28 May 2006 19:14:18 +0000 (GMT) (envelope-from imp@bsdimp.com) Received: from localhost (localhost.village.org [IPv6:::1] (may be forged)) by harmony.bsdimp.com (8.13.4/8.13.4) with ESMTP id k4SJC8ll095061; Sun, 28 May 2006 13:12:08 -0600 (MDT) (envelope-from imp@bsdimp.com) Date: Sun, 28 May 2006 13:12:12 -0600 (MDT) Message-Id: <20060528.131212.-1037137048.imp@bsdimp.com> To: netchild@freebsd.org From: "M. Warner Losh" In-Reply-To: <20060528123915.7fe8e278@Magellan.Leidinger.net> References: <20060527104539.1f4c0738@Magellan.Leidinger.net> <20060527200440.G79162@fledge.watson.org> <20060528123915.7fe8e278@Magellan.Leidinger.net> X-Mailer: Mew version 4.2 on Emacs 21.3 / Mule 5.0 (SAKAKI) Mime-Version: 1.0 Content-Type: Text/Plain; charset=us-ascii Content-Transfer-Encoding: 7bit Cc: cvs-src@freebsd.org, phk@phk.freebsd.dk, src-committers@freebsd.org, rwatson@freebsd.org, cvs-all@freebsd.org Subject: Re: cvs commit: src/sys/doc/subsys Dependencies Doxyfile-cam Doxyfile-crypto Doxyfile-dev_pci Doxyfile-dev_sound Doxyfile-dev_usb Doxyfile-geom Doxyfile-i4b Doxyfile-kern Doxyfile-libkern Doxyfile-linux Doxyfile-net80211 ... X-BeenThere: cvs-src@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: CVS commit messages for the src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 28 May 2006 19:14:20 -0000 In message: <20060528123915.7fe8e278@Magellan.Leidinger.net> Alexander Leidinger writes: : But when we have marked the internal functions as such, we can also : generate an official version without the internal functions. It's just : a switch. But so far I think we need to include everything until a : subsystem is fully documented. I think we should document everything and mark the *EXTERNAL* functions as such. I agree with your commentary about having full kernel docs, and approved API subset as well. However, kernel functions are by default internal unless we deside otherwise. : Since we have no API docs, everyone has to have a look at the kernel on : his own. This only provides a little bit of help here. We have api docs. Please don't say that we have none. There's a bunch of documentation in the man9 section of the man page. Sure, it is incomplete, misleading and obsolete in places, but it is documentation. : Since we are Open Source they can have a look and use unofficial parts : without our docs. But when we clearly say "this is for internal use : only", they can't moan. And we as developers have a benefit from the : docs too. I agree with this. I guess my only point of disagreement are the default sense of internal/external. Warner