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

[Daniel Vetter <daniel@ffwll.ch>]

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

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

- 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?
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch