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

[Daniel Vetter]

On Tue, May 13, 2014 at 9:17 AM, Thierry Reding
<thierry.reding at gmail.com> wrote:
> 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.

Not really sold on this, since in the end if we break userspace we
have to fix it up anyway. And all these properties are meant to be
used by userspace after all. I think for properties it's more
important to keep them all grouped together so that if new driver
writes look for something to use they don't reinvent a slight
variation of something existing again. Documentation/ABI otoh seems to
split things up per-knob, even across stable/testing/deprecated
directories.

Also eventually I want to pull these tables directly out of source
code comments - everything else tends to never get updated when the
code changes.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch