On Thu, 15 Dec 2016, Robert Bragg <rob...@sixbynine.org> wrote: > On Wed, Dec 14, 2016 at 7:17 PM, Jani Nikula > <jani.nik...@linux.intel.com> wrote: >> On Wed, 14 Dec 2016, Robert Bragg <rob...@sixbynine.org> wrote: >> The AST does include comments right above each cursor, but it falls >> short for comments not attached to cursors. You have to walk the tokens >> for that. I think I have most of this solved, though it hasn't seen much >> testing. > > Right, what I was thinking of though is that clang itself can actually > parse doxygen style comment sections like \brief, \param and \returns: > > http://clang.llvm.org/doxygen/classclang_1_1comments_1_1Parser.html > > Seems a bit mad, but this e.g. helps enable a -Wdocumentation warning > to check \params match actual function arguments > > I was wondering if that can somehow be exposed via the AST accessible > through the python bindings.
AFAICT this is not available via libclang or its python bindings; you can only get at the \brief paragraph, which does seems to indicate some parsing under the hood. I don't know if the information is available via some other clang interface, but even if it is, venturing outside of what python-clang provides makes both writing the tool and interfacing with Sphinx an order of magnitude more painful. Obviously -Wdocumentation working out of the box is nice, but apparently you'd have to use Doxygen anyway. Personally, I'm not interested in Doxygen compatibility or format. If you want that, you should probably use Doxygen. Oh, there's also cldoc [1], a documentation generator based on python-clang, but that invents another markdown based comment format and produces XML, neither of which work that great with Sphinx. I've looked at all of this before, and for *my* needs, aiming at a minimal python-clang based comment extractor that's mostly passthrough with some Sphinx C Domain directives sprinkled on top is the right choice. Kind of like autodoc for C, with no format conversions in between. And this is, of course, taking Sphinx for granted. Maybe even that is still open for you. BR, Jani. [1] https://jessevdk.github.io/cldoc/ -- Jani Nikula, Intel Open Source Technology Center _______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/mesa-dev
