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

[Randy Dunlap <rdunlap@infradead.org>]

On 05/12/2014 01:58 AM, Daniel Vetter wrote:
> On Mon, May 12, 2014 at 06:24:57PM +1000, Dave Airlie wrote:
>>>>
>>>> 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?
>>
>> Yeah I'm happy to block merging stuff, if we can spot new properties
>> when stuff is posted on dri-devel, so much the better,
>>
>> most drivers still send everything via dri-devel anyways, its only
>> really Intel I have to worry about so far,
> 
> I'll enforce that all prop stuff gets cc: dri-devel and that it has
> updates for the prop docs.
> 
>> But we should definitely add it to the new driver review checklist as well.
>>
>> I'm also on the side of this patch is ugly and makes my eyes burn,
>> please please get a plan to use something else ASAP, I'm willing to
>> merge this but I'm tempted to give it a lifetime of a kernel or two
>> before I burn it.
> 
> Ok, I'll try to move "make kerneldoc suck less" up the task list and maybe
> find someone to do it for me internally ;-)
> -Daniel
> 

I certainly have no objections to making kerneldoc suck less.
There was already an attempt to use asciidoc (like git uses) for kernel-doc
(a few years ago, by Sam Ravnborg).  I support(ed) that effort.

OTOH, I would only want to add another way to do kernel-doc if it can be a
full replacement for all of our docbook usage, i.e., it should provide a
way that we can eliminate docbook and stop using it completely.

thanks,
-- 
~Randy