[cfe-commits] [PATCH] libclang API for comment-to-xml conversion

[Douglas Gregor]

On Aug 7, 2012, at 11:01 AM, Dmitri Gribenko <gribozavr at gmail.com> wrote:

> On Mon, Aug 6, 2012 at 11:04 PM, Douglas Gregor <dgregor at apple.com> wrote:
>> On Aug 6, 2012, at 4:22 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
>>> Yes, I will add 'Other' for now, but at least 'Enum' should be added
>>> separately.  I think Protocols and categories can be handled as
>>> 'Class'es, properties -- as 'Variables'.  Of course, unless we want to
>>> store additional information for these.
>> 
>> Hrm, okay. We may need to separate out protocols later, because they are in a different namespace than (and, this this XML format, indistinguishable from) Objective-C classes.
> 
> OK.
> 
>>>> I assume that parameters (both template and function) will always be documented as part of their class/function/etc?
>>> 
>>> Yes, since \param and \tparam are in the same FullComment.
>> 
>> So, how does a client deal with this? Do they have to look at the cursor kind to decide whether to ask for a comment from elsewhere? Can we make it simpler?
> 
> I see two approaches to solve this particular one:
> 1. (manual) If the client also has a corresponding FunctionDecl,
> client can walk the children of root AST node and find parameter
> documentation.  No help with formatting, though.
> 
> 1. (transparent) Have ASTContext::getCommentForDecl walk up
> ParmVarDecl's DeclContext to find the FunctionDecl, then poke inside
> associated FullComment and create another FullComment with the found
> \param command as the child.  Creating a FullComment is required
> because currently we only attach FullComments to Decls.
> 
> 2. (not transparent) A separate API in libclang…

I'm liking the second #1 (transparently building a FullComment with just the parameter's documentation), actually.

>>>> I assume that "Function" elements need something for "throws" or "exceptions", but that's not at all important now.
>>> 
>>> Maybe we will pretty-print it as a part of declaration?  Added a TODO
>>> note for now.
>> 
>> It turns out that exceptions documented in Doxygen can have actual documentation paragraphs associated with them, so those won't be pretty-printed as part of the declaration.
> 
> Do you mean \throws or something else?  \throws should be easy to
> support in the same way as \param.

Yes, \throws (or \exception, or \throw). I expect it'll look like \param.

>> Thanks, patch LGTM!
> 
> Thank you for the review!  Committed r161431.

Thanks!

	- Doug