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

[Thierry Reding]

On Tue, May 13, 2014 at 09:34:45AM +0200, Daniel Vetter wrote:
> 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.

It's precisely because they are used by userspace that I think it's a
good idea to have them documented in a place where userspace developers
would look for them. I don't think anyone will look at the DRM docbook
because it's targetted at driver developers. That said there is a tiny
section called "Userland interfaces", so perhaps adding code to that and
pointing everyone at it would be an option. In which case I still think
we should follow some of the same guidelines as outlined in the ABI
documentation about deprecating and versioning properties. Keeping a
list of known users would also be great to have in case we ever need to
modify or want to remove ABI.

> 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.

I guess that's mostly a matter of convention. We could easily add a
"drm" subdirectory that contains the DRM property documentation. And in
my opinion having to scan a list of file names, such as:

	drm-connector-property-foo
	drm-plane-property-bar
	drm-plane-property-baz

isn't any more difficult than scanning the same list in docbook format.
So either way people will have to know where to look and then bother to
look in order for this to work. Whether it's in Documentation/ABI or
docbook is irrelevant.

Also there's a good reason for having the stable/testing/deprecated
split. That could also give additional hints as to whether it's a good
idea to add some property or not. If somebody were to add a property to
their driver that's been deprecated or removed for some other driver, a
look at the corresponding file should indicate why it was removed. That
could be valuable in pointing people in the right direction.

Similarly, if some property was documented in the stable subdirectory,
that would indicate that it's been deemed ready for prime time and give
more credibility. It also means that more userspace is likely to use it
and therefore might be higher priority to implement in new drivers.

> 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.

There are no guarantees that people will keep code comments up-to-date
either. The only way you can make sure of that is by reviewing patches
carefully. And if you do that, the same applies to external
documentation. I agree, though, that it's slightly easier to update code
comments, so if we can make this work together with some of the stricter
requirements for ABI as given above I think I could be happy as well.

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/24347885/attachment.sig>