On 08/01/14 05:58, 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 > ? > > Randy, could you please check whether your patch still applies and rebase and > resubmit it if it doesn't ? Hi Laurent, What patch are you referring to here? Thanks. >> 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. > -- ~Randy _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/intel-gfx
