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

[Laurent Pinchart]

Hi Randy,

On Thursday 31 July 2014 15:16:21 Randy Dunlap wrote:
> 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 ;-)
> >>> 
> >>> 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.

I agree with you, there's no reason to block your patch just because we might 
get a better documentation tool at a still unknown point in the future. 
Daniel, are you fine with merging the documentation in DocBook format for now 
?

Randy, could you please check whether your patch still applies and rebase and 
resubmit it if it doesn't ?

> 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.

-- 
Regards,

Laurent Pinchart