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 _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx http://lists.freedesktop.org/mailman/listinfo/intel-gfx
