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

[Ville Syrjälä]

On Wed, Mar 12, 2014 at 12:25:06PM +0100, Laurent Pinchart wrote:
> Hi Sagar,
> 
> On Wednesday 12 March 2014 16:46:05 Sagar Arun Kamble wrote:
> > On Mon, 2014-03-10 at 15:36 +0100, Laurent Pinchart wrote:
> > > On Monday 10 March 2014 06:21:49 Daniel Vetter wrote:
> > > > On Wed, Mar 5, 2014 at 11:56 AM,  <sagar.a.kamble at intel.com> wrote:
> > > > > +<table border="1" cellpadding="0" cellspacing="0" >
> > > > > +<tbody>
> > > > > +<tr style="font-weight: bold;" >
> > > > > +<td valign="top" >Owner Module/Drivers</td>
> > > > > +<td valign="top" >Group</td>
> > > > > +<td valign="top" >Property Object</td>
> > > > > +<td valign="top" >Property Name</td>
> > > > > +<td valign="top" >Type</td>
> > > > > +<td valign="top" >Property Values</td>
> > > > > +<td valign="top" >Object attached</td>
> > > > > +<td valign="top" >Description</td>
> > > > > +</tr>
> > > > 
> > > > In my opinion this is a horrible way to write property documentations
> > > > - explicitly constructing html tables is error prone and really hard
> > > > to read in the source. Imo docbook in general is rather horrible,
> > > > which is way I write almost all my docs as kerneldoc ;-)
> > > > 
> > > > I think a simple asciidoc/markdown would be much simpler, with a bit
> > > > of free-form structure to group properties into relevant groups.
> > > > Long-term we might even need to split it up into different spec files
> > > > to keep a good overview.
> > > 
> > > Docbook is indeed hard to read and write when it comes to such tables.
> > > However I like having the properties documented in the DRM core
> > > documentation. Maybe we could come up with a simpler text format that
> > > would be transformed into docbook when compiling the documentation ?
> > 
> > Does this mean we need to create comment block with "Doc: drm
> > properties" style section in each driver where drm properties are
> > instantiated. And then in drm.tmpl collect all these using !P escape
> > sequence?
> > How do create table out of these across all drivers?
> 
> I don't have a strong preference here. Documenting properties in source code 
> comments would be fine, so would an external central documentation file in a 
> non Docbook format. For the record I'm personally fine with using Docbook as 
> in this patch :-)
> 
> If we decide to go for property documentation inside the source code then I 
> believe we'll have to create our own format, as creating a properties table 
> from kerneldoc information extracted from comments is probably not possible.

Can comeone pick up the ball here and figure out what needs to be done?

The reason why I want a central place for the documentation is to force
people to collaborate outside their own sandbox when adding properties.
Whether that's docbook or some text file I don't care so much at this
point. The fact that it's a central place should mandate that the
patches changing it will go through dri-devel and so everyone should se
them, and when adding new properties it would make the patch author more
likely to look around a bit before adding another slighty incompatible
version of the same property. If someone has a better suggestion how to
encforce this I'm all ears.

Of course this idea can still fail if our esteemed maintainer merges
stuff without checking for violations of this policy. Dave, any thoughts
on the subject?

Either way I can tell you that I'm not very enthusiastic about reviewing
any property patches until some kind of decision about this is reached,
be it "docbook", "text", "plan c", or "fuck it, let the world burn!".

-- 
Ville Syrjälä
Intel OTC