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

[Laurent Pinchart]

On Monday 04 August 2014 09:30:04 Daniel Vetter wrote:
> On Fri, Aug 01, 2014 at 02:58:21PM +0200, Laurent Pinchart wrote:
> > 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 ...

Sorry, my bad, I should have checked that. And the patch doesn't originate 
from Randy, double screw-up... *sigh* sorry for the noise.

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

-- 
Regards,

Laurent Pinchart