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