Re: [PATCH 1/1] Documentation: drm: describing drm properties exposed by various drivers

[Daniel Vetter <daniel@ffwll.ch>]

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

> 
> 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@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@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@lists.freedesktop.org
> > > http://lists.freedesktop.org/mailman/listinfo/dri-devel
> 
> 

-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch