From owner-freebsd-doc@FreeBSD.ORG Wed Dec 7 07:27:25 2011 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 9D3C0106566B for ; Wed, 7 Dec 2011 07:27:25 +0000 (UTC) (envelope-from stb@lassitu.de) Received: from gilb.zs64.net (gilb.zs64.net [IPv6:2001:470:1f0b:105e::1ea]) by mx1.freebsd.org (Postfix) with ESMTP id 64E718FC14 for ; Wed, 7 Dec 2011 07:27:25 +0000 (UTC) Received: by gilb.zs64.net (Postfix, from stb@lassitu.de) id 239B21157E2; Wed, 7 Dec 2011 08:27:24 +0100 (CET) Mime-Version: 1.0 (Apple Message framework v1251.1) Content-Type: text/plain; charset=windows-1252 From: Stefan Bethke In-Reply-To: Date: Wed, 7 Dec 2011 08:27:23 +0100 Content-Transfer-Encoding: quoted-printable Message-Id: References: <77AB0982-9E21-4BB3-8CE5-E390112E27B8@lassitu.de> <176FCC23-A2BB-4C51-8219-A3D06515A30C@lassitu.de> To: Benjamin Kaduk X-Mailer: Apple Mail (2.1251.1) Cc: freebsd-doc Subject: Re: Documenting device driver methods X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 07 Dec 2011 07:27:25 -0000 Am 07.12.2011 um 06:56 schrieb Benjamin Kaduk: > On Tue, 6 Dec 2011, Stefan Bethke wrote: >=20 >>=20 >> Am 06.12.2011 um 15:34 schrieb Stefan Bethke: >>=20 >>> I noticed that very few (if any) device drivers have their interface = methods documented (e.g. iicbus, iicbb, gpiobus, gpio). >>>=20 >>> Where should such documentation go? In the driver specific man page, = in a separate section 9 page per method, or a single section 9 man page? >>>=20 >>> Is there a preferred style for these? >>=20 >> Would it make sense to document device classes in the device section = with the class name in all capitals, e.g. foo_if.m as FOO.4? >=20 > My 0.02 would be a single section 4 page per driver, but with a bunch = of MLINKS for the methods, and cross-ref'd from the driver page. The = driver page seems to be more of an overview of the thing as a whole and = not really a programming guide. Though, that might lead one to put it = in section 9 =85 There are interfaces for which there is no "main" driver, for example, = iic_if.m or mii_if.m. For mii_if.m, there is a man/man4/mii.4 page that = describes the interfaces. In case of iic_if.m that woulnd't work since = there is a dev/iicbus/iic.c character device driver with it's own man = page iic(4). Hence my suggestion to "create a new namespace" for the = interfaces themselves. Using iic_if as the man page name would also be = a possibility. Stefan --=20 Stefan Bethke Fon +49 151 14070811