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

[Laurent Pinchart]

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.

-- 
Regards,

Laurent Pinchart