From owner-cvs-src@FreeBSD.ORG Sat May 27 19:10:26 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 E74F816B7F2; Sat, 27 May 2006 19:10:26 +0000 (UTC) (envelope-from rwatson@FreeBSD.org) Received: from cyrus.watson.org (cyrus.watson.org [209.31.154.42]) by mx1.FreeBSD.org (Postfix) with ESMTP id A096643D95; Sat, 27 May 2006 19:09:55 +0000 (GMT) (envelope-from rwatson@FreeBSD.org) Received: from fledge.watson.org (fledge.watson.org [209.31.154.41]) by cyrus.watson.org (Postfix) with ESMTP id 0FAB046BD6; Sat, 27 May 2006 15:09:55 -0400 (EDT) Date: Sat, 27 May 2006 20:09:54 +0100 (BST) From: Robert Watson X-X-Sender: robert@fledge.watson.org To: Alexander Leidinger In-Reply-To: <20060527104539.1f4c0738@Magellan.Leidinger.net> Message-ID: <20060527200440.G79162@fledge.watson.org> References: <20060526204457.3e545e4f@Magellan.Leidinger.net> <11534.1148678206@critter.freebsd.dk> <20060527104539.1f4c0738@Magellan.Leidinger.net> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: cvs-src@FreeBSD.org, Poul-Henning Kamp , src-committers@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: Sat, 27 May 2006 19:10:39 -0000 On Sat, 27 May 2006, Alexander Leidinger wrote: >> Can we agree that no functions will be put into publicized documentation >> until somebody has considered if the function actually is a public function >> or not ? > > Does this mean you want to have everything marked as "@internal" by default? > I don't think there's a switch which does this, so you would have to mark > every function with @internal by hand. This sounds very worrying. > What about adding a comment to the pages which tells everyone that we are > working on this documentation and so far we haven't reviewed every function > and decided if it is an internal one or not. > > And the most important point is: what does it mean if a function is > internal? Does it mean 3rd party developers are not allowed to use them, but > committers are free to use it? Or does it mean nobody is allowed to use them > except they are used in the same subsystem (or even only in a small part of > the subsystem as specified in the docu of the functions)? Who is this documentation for? If it's for us, then it should document everything. But if it's for third party developers, it certainly should not document everything. Over the last few years, we've been informally working to refine the set of functions and symbols depended on by device drivers, and on several occasions we've had discussions about taking this much more seriously. If you want an example of one way to approach this, take a look at Apple's KPI drive. They explicitly document which functions, data structures, definitions, etc, may be depended on by drivers of particular types. This helps to eliminate ABI breakage across versions, allowing device drivers to work on many versions of Mac OS X. As a general rule, third party code should only use documented KPIs, or it will risk getting broken due to API changes (and no longer compile) or due to ABI changes (where the code compiles but may corrupt kernel data structures). If we want to support third party device driver vendors better, we need to take this issue more seriously. For that matter, if we even want books on how to write device drivers, we need to take it seriously! So if this is documentation for use by developers modifying the code without a concern about APIs and ABIs changing, this is fine. But it cannot be documentation for third party developers writing to any of our pluggable/loadable interfaces in its current form, because that documentation is by definition exclusive, not inclusive -- things should only appear in it when explicitly intended to be there. Robert N M Watson