Documenting device driver methods

[Stefan Bethke]

Am 07.12.2011 um 06:56 schrieb Benjamin Kaduk:

> On Tue, 6 Dec 2011, Stefan Bethke wrote:
> 
>> 
>> Am 06.12.2011 um 15:34 schrieb Stefan Bethke:
>> 
>>> I noticed that very few (if any) device drivers have their interface methods documented (e.g. iicbus, iicbb, gpiobus, gpio).
>>> 
>>> 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?
>>> 
>>> Is there a preferred style for these?
>> 
>> 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?
> 
> 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 …


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

-- 
Stefan Bethke <stb at lassitu.de>   Fon +49 151 14070811