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

[Rob Clark]

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