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

[Sagar Arun Kamble]

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.

thanks,
Sagar


On Sat, 2014-05-10 at 06:56 -0400, Rob Clark wrote:
> On Sat, May 10, 2014 at 6:39 AM, Ville Syrjälä
> <ville.syrjala at linux.intel.com> wrote:
> > 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!".
> 
> any of the first three options would be vastly superior to what we do now
> 
> tbh, I'd suggest imposing a no-new-properties-without-docs rule even
> if we haven't finished bikeshedding about the docs format.  That might
> motivate someone to hurry up and just pick one.
> 
> We can change the format, figure out some way to get it into docbook,
> etc, later.. it's not such a huge volume of words we have to type here
> that we can't reformat it later.
> 
> BR,
> -R
> 
> 
> >
> > --
> > Ville Syrjälä
> > Intel OTC
> > _______________________________________________
> > dri-devel mailing list
> > dri-devel at lists.freedesktop.org
> > http://lists.freedesktop.org/mailman/listinfo/dri-devel