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
