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

[Laurent Pinchart]

Hi Daniel,

On Tuesday 13 May 2014 09:34:45 Daniel Vetter wrote:
> On Tue, May 13, 2014 at 9:17 AM, Thierry Reding 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.

On the subject of moving documentation from docbook to source code, do your 
kerneldoc extensions plans include supporting images ? A drawing is worth a 
thousand words (see http://linuxtv.org/downloads/v4l-dvb-apis/subdev.html#subdev-image-processing-scaling-multi-source for instance), 
and that's currently a pretty important feature of the docbook format.

-- 
Regards,

Laurent Pinchart