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

[Daniel Vetter <daniel@ffwll.ch>]

On Fri, Aug 01, 2014 at 02:58:21PM +0200, Laurent Pinchart wrote:
> 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 
> ?

It was already merged ... My mail was really just to make people aware of
what I'd like to have (and what I'll try to get) so that could coordinate
(if other people also work on this).
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch