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

[Randy Dunlap <rdunlap@infradead.org>]

On 05/12/14 11:04, Randy Dunlap wrote:
> On 05/12/2014 08:54 AM, Daniel Vetter wrote:
>> On Mon, May 12, 2014 at 08:23:45AM -0700, Randy Dunlap wrote:
>>> 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.
>>
>> Hm, do you have pointers to those? My google-fu seems lacking ...
> 
> I googled for /kernel doc asciidoc ravnborg/ and found several hits for them.
> 
>> Ok, let's move this to the top and start discussions. The past few months
>> I've written piles of kerneldoc comments for the DRM DocBook (all pulled
>> in as kerneldoc, docbook .tmpl has just the chapter structure). DOC:
>> sections are really useful to pull all the actual documentation out of the
>> docbook xml into kerneldoc.
>>
>> But I've also done piles of docs for intel-gpu-tools, which is using
>> gtkdoc. And there are some clear deficiencies:
>>
>> - No markdown for inline coments. Lack of lists and tables is hurting
>>   especially badly. If we add this (and I don't care one iota whether it's
> 
> Yes, I've tried to add lists to kernel-doc notation but have failed so far.
> 
>>   markdown or asciidoc or something else as long as it's readable plain
>>   text in comments) we should be able to move all the existing docbook xml
>>   paragraphs/lists/tables into kerneldoc comments.
>>
>> - Automatic cross-referencing of functions. If you place e.g. function()
>>   or #struct anywhere in a documentation comment gtk-doc automatically
>>   inserts a hyperlink to the relevant documentation page across the entire
>>   project. Really powerful and makes overview sections much more useful
>>   entry points for beginners since they can easily jump back&forth
>>   betweeen the high-level overview and low-level per-function
>>   documentation.
>>
> 
> That's a nice-to-have IMO, but a really nice one.
> 
>> - In a really perfect world it would help if kerneldoc could collect
>>   structure member kerneldoc from per-member comments. Especially for
>>   large structures with lots of comments this would bring the kerneldoc
>>   and struct member much closer together.
>>
>> So that's my wishlist.
>>  
>>> 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.
>>
>> Hm, I don't mind docbook at all, as long as all the real content is
>> embedded into source files as kerneldoc and the docbook template just
>> pulls in all the right bits and pieces. Even gtkdoc allos you to do that
>> and pull in the different libararies (== header files with declarations
>> for C) in the order you want. So imo the docbook toolchain is good enough
>> for my needs.
>>
>> Or what do you mean by getting rid of all docbook usage?
> 
> I meant no docbook style sheets, no 'xmlto', the whole ball of wax.
> 
> But primarily I don't want to see drivers/video/ using one set of doc tools
> and drivers/media/ using another set and drivers/xyz/ using its own set of
> tools, etc. etc. etc.

Hi Daniel and others,

I don't know what your plans are for drm docs (tables, etc.), but I think that
I misspoke above.   My primary/major concern is that there be some useful
documentation.  What form or format it is in is secondary.

It's not a good thing that media DocBook is so different from all of the
others, but it's OK.

It's not a good thing that drivers/lguest/ uses its own tools to extract
comments from source files to create documentation, but it's OK -- at least
it generates some (hopefully useful) documentation.

I also note that a new autofs doc file (not yet merged) uses markdown.

Please feel free to use kernel-doc or markdown or asciidoc or plain text. :)
or even your own tools, even though that is less preferred.


Thanks.

-- 
~Randy