[cfe-dev] libclang documentation/comments API

[Kevin Funk via cfe-dev]

On Sunday, September 06, 2015 05:54:01 PM Ben Jackson via cfe-dev wrote:
> 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 <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>) 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. :) If anyone is interested, a quick
> demo is here: http://www.gfycat.com/AlertNarrowAntelopegroundsquirrel
> <http://www.gfycat.com/AlertNarrowAntelopegroundsquirrel>

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

> Many thanks,
> Ben
> 
> P.S. Apologies if this list is not for this sort of query :/

-- 
Kevin Funk | kfunk at kde.org | http://kfunk.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 181 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.llvm.org/pipermail/cfe-dev/attachments/20150906/b3d0f98f/attachment.sig>