<div dir="auto"><div><div class="gmail_extra"><div class="gmail_quote">On Dec 15, 2016 6:40 AM, "Jani Nikula" <<a href="mailto:jani.nikula@linux.intel.com">jani.nikula@linux.intel.com</a>> wrote:<br type="attribution"><blockquote class="quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="quoted-text">On Thu, 15 Dec 2016, Robert Bragg <<a href="mailto:robert@sixbynine.org">robert@sixbynine.org</a>> wrote:<br>
> On Wed, Dec 14, 2016 at 7:17 PM, Jani Nikula<br>
> <<a href="mailto:jani.nikula@linux.intel.com">jani.nikula@linux.intel.com</a>> wrote:<br>
>> On Wed, 14 Dec 2016, Robert Bragg <<a href="mailto:robert@sixbynine.org">robert@sixbynine.org</a>> wrote:<br>
</div><div class="quoted-text">>> The AST does include comments right above each cursor, but it falls<br>
>> short for comments not attached to cursors. You have to walk the tokens<br>
>> for that. I think I have most of this solved, though it hasn't seen much<br>
>> testing.<br>
><br>
> Right, what I was thinking of though is that clang itself can actually<br>
> parse doxygen style comment sections like \brief, \param and \returns:<br>
><br>
> <a href="http://clang.llvm.org/doxygen/classclang_1_1comments_1_1Parser.html" rel="noreferrer" target="_blank">http://clang.llvm.org/doxygen/<wbr>classclang_1_1comments_1_<wbr>1Parser.html</a><br>
><br>
> Seems a bit mad, but this e.g. helps enable a -Wdocumentation warning<br>
> to check \params match actual function arguments<br>
><br>
> I was wondering if that can somehow be exposed via the AST accessible<br>
> through the python bindings.<br>
<br>
</div>AFAICT this is not available via libclang or its python bindings; you<br>
can only get at the \brief paragraph, which does seems to indicate some<br>
parsing under the hood. I don't know if the information is available via<br>
some other clang interface, but even if it is, venturing outside of what<br>
python-clang provides makes both writing the tool and interfacing with<br>
Sphinx an order of magnitude more painful.<br>
<br>
Obviously -Wdocumentation working out of the box is nice, but apparently<br>
you'd have to use Doxygen anyway. Personally, I'm not interested in<br>
Doxygen compatibility or format. If you want that, you should probably<br>
use Doxygen.<br>
<br>
Oh, there's also cldoc [1], a documentation generator based on<br>
python-clang, but that invents another markdown based comment format and<br>
produces XML, neither of which work that great with Sphinx.<br>
<br>
I've looked at all of this before, and for *my* needs, aiming at a<br>
minimal python-clang based comment extractor that's mostly passthrough<br>
with some Sphinx C Domain directives sprinkled on top is the right<br>
choice. Kind of like autodoc for C, with no format conversions in<br>
between. And this is, of course, taking Sphinx for granted. Maybe even<br>
that is still open for you.<br></blockquote></div></div></div><div dir="auto"><br></div><div dir="auto">Dylan and I talked about a couple of possibilities for how to tie things into sphinx.  One was to come up with some regex and do a mass conversion of the tree from doxygen to sphinx rst. Another was use that same regex as a filter that gets applied as you pull from the source.  I think we'll have to do since experimentation to figure out the best approach.  Right now, Mesa doesn't really make full use of doxygen so regex is probably tractable.</div><div dir="auto"><br></div><div dir="auto">We've also talked about some of the doxygen-based solutions such as breathe.  Personally, though, I'd rather get rid of the middle man.</div></div>