Date: Wed, 7 Dec 2011 08:27:23 +0100 From: Stefan Bethke <stb@lassitu.de> To: Benjamin Kaduk <kaduk@MIT.EDU> Cc: freebsd-doc <freebsd-doc@freebsd.org> Subject: Re: Documenting device driver methods Message-ID: <CF7A562A-3288-4D56-AE7D-5E868801422B@lassitu.de> In-Reply-To: <alpine.GSO.1.10.1112070051430.882@multics.mit.edu> References: <77AB0982-9E21-4BB3-8CE5-E390112E27B8@lassitu.de> <176FCC23-A2BB-4C51-8219-A3D06515A30C@lassitu.de> <alpine.GSO.1.10.1112070051430.882@multics.mit.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
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 <stb@lassitu.de> Fon +49 151 14070811
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?CF7A562A-3288-4D56-AE7D-5E868801422B>