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@xxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
