On Fri, Dec 09, 2016 at 12:41:08PM +0000, Robert Bragg wrote: > On Thu, Dec 8, 2016 at 3:53 PM, Daniel Vetter <daniel@xxxxxxxx> wrote: > > On Wed, Dec 07, 2016 at 09:40:33PM +0000, Robert Bragg wrote: > >> This adds a 'Perf' section to i915.rst with the following sub sections: > >> - Overview > >> - Comparison with Core Perf > >> - i915 Driver Entry Points > >> - i915 Perf Stream > >> - i915 Perf Observation Architecture Stream > >> - All i915 Perf Internals > >> > >> v2: > >> section headers in i915.rst (Daniel Vetter) > >> missing symbol docs + other fixups (Matthew Auld) > >> > >> Signed-off-by: Robert Bragg <robert@xxxxxxxxxxxxx> > >> Reviewed-by: Matthew Auld <matthew.auld@xxxxxxxxx> > >> Cc: Daniel Vetter <daniel.vetter@xxxxxxxx> > > > > Obligatory bikeshed about explicitly listening all functions, but hey > > great docs, I'll merge ;-) > > Yeah, understood. > > Not sure if you saw my last reply to this, but I think listing symbols > explicitly is appropriate for documentation, where the ordering and > groupings of symbols for the sake of introducing them in logical > stages doesn't necessarily match that found in code. > > Not perfect in itself but having worked with gtk-doc in the past I > thought it made sense, and worked reasonably enough, to explicitly > list section headers and symbols in a sections.txt file to control the > order things are presented to developers. Of course we sometimes > forgot to add new symbols to the sections.txt file which is a trade > off, but it never seemed like that big of an issue, compared to having > the extra editorial control over your docs. It's a trade-off, and given how bad we are with keeping docs up-to-date I'm heavily in favour of optimizing for that over perfectly looking docs. If we'd have a full-time doc tech writer to help maintain this I wouldn't bikeshed at all ;-) btw 0day spotted an issue in your patch, I didn't look at it though. > Jani's comment was also fair about the fact that the current approach > results in lots of runs of the kernel-doc script, but that one really > seems like an implementation detail where we should avoid compromising > docs to workaround the tools (ofc just my interpretation that it would > be a compromise). I did half consider modifying kernel-doc to allow > for the -functions argument to take an ordered list instead of a set, > but couldn't quite muster the energy to modify a perl script :-p > > As a bit of an asside; last year for another project of mine I once > wrote an experimental tool for extracting gtk-doc comments from code > to using the python clang bindings: > https://github.com/rib/clib/blob/master/site/rst-from-c.py > > It's crossed my mind to play around with being able to extract > kernel-doc with clang along similar lines which could potentially > track more type information so the docs could support more than just > .. c:function and .. c:type, such as c:macro and c:member and could > better handle things like function pointers as members of structs. > Maybe it's an idea worth considering. Talk to Jani, he has it implemented already somewhere. But kernel-doc is a horrible, and we have about 50k existing comments that all need to still parse, so it's really tricky to move forward. -Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch _______________________________________________ Intel-gfx mailing list Intel-gfx@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx
