On Mon, May 12, 2014 at 10:03:55AM +0200, Daniel Vetter wrote: > On Mon, May 12, 2014 at 11:37:53AM +0530, Sagar Arun Kamble wrote: > > I support approach using docbook to start since there are not lot of > > properties. Laurent has ack'ed this one. Can we go ahead with this? > > http://lists.freedesktop.org/archives/intel-gfx/2014-March/041527.html > > > > Adding description of new property is not very complex (assuming table > > format is understood and being comfortable with HTML row/table > > manipulation). > > > > Adding description of each property in their source might be time > > consuming task. > > Yeah I'm ok with docbook for the time being. My long-term plan is to fix > up kerneldoc to support markdown and then we can move such neat tables > into the code. There's lots other places that would benefit from proper > list formatting and tables. So Ack from my side on both the docbook patch > and the no-more-props-without-doc-patch rule (which is kinda what I've > been doing thus far). What happened to the proposal to add this to the Documentation/ABI directory? That already contains a bunch of files describing userspace ABI (although most of it is sysfs-related). The objection that I have to including property documentation in docbook is that the DRM docbook is documentation targetted at driver developers, but properties are userspace ABI. Therefore I think we should be using mechanisms that have been used to document other userspace ABI before to make it easier for people to find (and for consistency). One big advantage in using Documentation/ABI is that there's a fairly well documented process of how to add, deprecate and remove ABI. There's also a template that should be followed when writing these files. People have obviously put some thought into this before, so it would be a bit of a waste trying to come up with our own. The README file has some good information about all of this and I think it matches what we need fairly well. In particular I like the concept of the "Users" section, which could save us a lot of work trying to track potential users of crufty ABI retrospectively. Thierry
Attachment:
pgppz6qTtjPMW.pgp
Description: PGP signature
