libclang documentation/comments API

Hi there,

I’m working on a feature for querying and returning documentation data in a libclang-based code comprehension engine (ycmd - https://github.com/Valloric/ycmd ). The idea is, for a given cursor, return meaningful documentation for display to a user in their IDE (i.e. “What is the doxygen documentation for the method under my cursor?” ).

I have found that there is quite rich support for doxygen comment parsing within clang, and most (all?) of it is exposed in libclang. This is awesome! Thanks!

However, I do have a few questions about the current level of support:

  1. The “comment introspection” API is not listed (here: http://clang.llvm.org/doxygen/modules.html) as part of “libclang”. Does that mean that the API is not public or not stable in some way? The docs say “These facilities are distinct from the core and may be subject to their own schedule of stability and deprecation”… I’m just curious as to how much this is likely to be an issue?

  2. Is there any way via libclang to get the raw text, or any other pretty-printed text, of a particular declaration? The idea here is that I could present the declaration text, followed by its brief and any other documentation. The declaration text itself is probably the most useful documentation for a developer :).Currently I am actually getting this by calling clang_FullComment_getAsXML() and parsing the output to get the “” element, but that seems painfully wasteful.

  3. I guess finally, do you have any other thoughts or has anyone approached this before or know of an implementation doing this sort of thing, etc. Any feedback would be greatly appreciated. :slight_smile: If anyone is interested, a quick demo is here: http://www.gfycat.com/AlertNarrowAntelopegroundsquirrel

Many thanks,
Ben

P.S. Apologies if this list is not for this sort of query :confused:

Hi there,

I’m working on a feature for querying and returning documentation data in a
libclang-based code comprehension engine (ycmd -
https://github.com/Valloric/ycmd ). The
idea is, for a given cursor, return meaningful documentation for display to
a user in their IDE (i.e. “What is the doxygen documentation for the method
under my cursor?” ).

I have found that there is quite rich support for doxygen comment parsing
within clang, and most (all?) of it is exposed in libclang. This is
awesome! Thanks!

However, I do have a few questions about the current level of support:

1. The “comment introspection” API is not listed (here:
http://clang.llvm.org/doxygen/modules.html
<http://clang.llvm.org/doxygen/modules.html&gt;\) as part of “libclang”. Does
that mean that the API is not public or not stable in some way? The docs
say “These facilities are distinct from the core and may be subject to
their own schedule of stability and deprecation”… I’m just curious as to
how much this is likely to be an issue?

2. Is there any way via libclang to get the raw text, or any other
pretty-printed text, of a particular declaration? The idea here is that I
could present the declaration text, followed by its brief and any other
documentation. The declaration text itself is probably the most useful
documentation for a developer :).Currently I am actually getting this by
calling clang_FullComment_getAsXML() and parsing the output to get the
“<Declaration>” element, but that seems painfully wasteful.

As last resort, we in KDevelop have our brute-force method of extracting raw
text from a source range, see ClangUtils::getRawContents here:
  https://quickgit.kde.org/?p=kdev-clang.git&a=blob&hb=HEAD&f=util
%2Fclangutils.cpp
  (not the most performant solution either, but helps getting "what the user
wrote")

3. I guess finally, do you have any other thoughts or has anyone approached
this before or know of an implementation doing this sort of thing, etc. Any
feedback would be greatly appreciated. :slight_smile: If anyone is interested, a quick
demo is here: http://www.gfycat.com/AlertNarrowAntelopegroundsquirrel
<http://www.gfycat.com/AlertNarrowAntelopegroundsquirrel&gt;

We already use it in kdev-clang as well. In our case we simply show the
documentation in the context browser popup in case the user a) hovers a
declaration with the mouse, or b) presses "Alt" when over a declaration with
the cursor. (Alt+Keys then also allows navigation within the popup).

See here:
  http://i.imgur.com/zF17xrk.png

Cheers

Hi there,

I’m working on a feature for querying and returning documentation data in a libclang-based code comprehension engine (ycmd - https://github.com/Valloric/ycmd ). The idea is, for a given cursor, return meaningful documentation for display to a user in their IDE (i.e. “What is the doxygen documentation for the method under my cursor?” ).

\o/ Awesome

I have found that there is quite rich support for doxygen comment parsing within clang, and most (all?) of it is exposed in libclang. This is awesome! Thanks!

However, I do have a few questions about the current level of support:

  1. The “comment introspection” API is not listed (here: http://clang.llvm.org/doxygen/modules.html) as part of “libclang”. Does that mean that the API is not public or not stable in some way? The docs say “These facilities are distinct from the core and may be subject to their own schedule of stability and deprecation”… I’m just curious as to how much this is likely to be an issue?

Unlikely to be an issue. I think the case is simply that the comment parsing stuff is newer than a lot of the things that are considered very very stable.