From owner-freebsd-doc@FreeBSD.ORG Wed Dec 7 05:56:34 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 811FB106566B for ; Wed, 7 Dec 2011 05:56:34 +0000 (UTC) (envelope-from kaduk@mit.edu) Received: from dmz-mailsec-scanner-8.mit.edu (DMZ-MAILSEC-SCANNER-8.MIT.EDU [18.7.68.37]) by mx1.freebsd.org (Postfix) with ESMTP id 2130B8FC12 for ; Wed, 7 Dec 2011 05:56:33 +0000 (UTC) X-AuditID: 12074425-b7f116d0000008fe-de-4edf00100c11 Received: from mailhub-auth-4.mit.edu ( [18.7.62.39]) by dmz-mailsec-scanner-8.mit.edu (Symantec Messaging Gateway) with SMTP id 0C.42.02302.0100FDE4; Wed, 7 Dec 2011 00:56:33 -0500 (EST) Received: from outgoing.mit.edu (OUTGOING-AUTH.MIT.EDU [18.7.22.103]) by mailhub-auth-4.mit.edu (8.13.8/8.9.2) with ESMTP id pB75uW5N018527; Wed, 7 Dec 2011 00:56:32 -0500 Received: from multics.mit.edu (MULTICS.MIT.EDU [18.187.1.73]) (authenticated bits=56) (User authenticated as kaduk@ATHENA.MIT.EDU) by outgoing.mit.edu (8.13.6/8.12.4) with ESMTP id pB75uS7d007467 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT); Wed, 7 Dec 2011 00:56:30 -0500 (EST) Received: (from kaduk@localhost) by multics.mit.edu (8.12.9.20060308) id pB75uSmr004631; Wed, 7 Dec 2011 00:56:28 -0500 (EST) Date: Wed, 7 Dec 2011 00:56:28 -0500 (EST) From: Benjamin Kaduk To: Stefan Bethke In-Reply-To: <176FCC23-A2BB-4C51-8219-A3D06515A30C@lassitu.de> Message-ID: References: <77AB0982-9E21-4BB3-8CE5-E390112E27B8@lassitu.de> <176FCC23-A2BB-4C51-8219-A3D06515A30C@lassitu.de> User-Agent: Alpine 1.10 (GSO 962 2008-03-14) MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Brightmail-Tracker: H4sIAAAAAAAAA+NgFnrJIsWRmVeSWpSXmKPExsUixG6nrivIcN/P4NdBRotTZ7pYLU4fWsDm wOQx49N8Fo9Fc/8zBTBFcdmkpOZklqUW6dslcGVs2n2OraCZveL21wbWBsbdrF2MnBwSAiYS /94/ZIOwxSQu3FsPZHNxCAnsY5S4frKJBcJZzyhx5tQ6RpAqIYH9TBLHHhR3MXIA2fUS+6fX g4RZBLQkLj5awgxiswmoSMx8sxFsqIiAksTZKbfBWpkFNCUOb37GBGILC+hJ7Dj0hAlkDKeA ncTb9kCQMK+AvcSZTd8YIabnS5xdCdYpKqAjsXr/FBaIEkGJkzOfsEBMtJQ49+c62wRGwVlI UrOQpBYwMq1ilE3JrdLNTczMKU5N1i1OTszLSy3StdDLzSzRS00p3cQIDlEX1R2MEw4pHWIU 4GBU4uHd4HDPT4g1say4MvcQoyQHk5Io79RfQCG+pPyUyozE4oz4otKc1OJDjBIczEoivPnJ QDnelMTKqtSifJiUNAeLkjjv6x0OfkIC6YklqdmpqQWpRTBZGQ4OJQneWf+AGgWLUtNTK9Iy c0oQ0kwcnCDDeYCGnwGp4S0uSMwtzkyHyJ9iVJQS5+0ASQiAJDJK8+B6YSnkFaM40CvCvEtA qniA6Qeu+xXQYCagwXxRd0EGlyQipKQaGK0nTc5LY76RH5FRqG7M/v1H+juDHvmqkKnPvM2f r+TPzNGXr89evv/HbiVW0/0WXuUbX0S+/3U5TmL6DTbGVWyVEsHZ6bpXX658M/PDwYJuS3kr ltN8l2a9/HH39uHWx+GCouEW/6Rbo8+zCUZ5fFT3vXXrwUmhtLrvaQqNjLP+vXHOYVpZrsRS nJFoqMVcVJwIAGR3GvH8AgAA 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 05:56:34 -0000 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 ... -Ben Kaduk