[Intel-gfx] [PATCH] drm/i915/perf: More documentation hooked to i915.rst

[Jani Nikula]

On Mon, 12 Dec 2016, Daniel Vetter <daniel at ffwll.ch> wrote:
> On Fri, Dec 09, 2016 at 12:41:08PM +0000, Robert Bragg wrote:
>> 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.

Yeah, I admit to having a little side project to use python-clang to
extract documentation comments directly into Sphinx.

But I've pretty much decided I'm not going to pursue making it a
replacement for kernel-doc. There is no point in that unless it has a
chance of being merged upstream, and I think depending on clang is a
non-starter for that. I'm just totally disinterested in having that
discussion.

Instead, I'm trying to make it a really small and clean alternative for
Doxygen in Sphinx based documentation.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center