[Intel-gfx] [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers

[Thierry Reding]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://lists.freedesktop.org/archives/intel-gfx/attachments/20140513/40c68f0f/attachment.sig>