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

[Dmitri Gribenko]

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...

>>> Similarly, enumerators will be documented as part of their enumeration type?
>>
>> No, since enums are usually documented this way:
>> /// Blah
>> enum A {
>>   A1, ///< Aaa
>>   A2, ///< Bbb
>> };
>> So comments for enumerators end up in separate FullComments.
>
> Will these be classified as "variables", then, for the XML representation?

Currently they are "other".  Makes sense to change to variable.

>>> What should happen if one asks for the XML representation of, e.g., a parameter's comment?
>>
>> For ParmVarDecl, ASTContext::getRawCommentForDeclNoCache() will fail
>> even to find a RawComment.
>
> Okay. I guess that ties in with the question of "how should the client handle this?"

See above.

>>> 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.

>>> Similarly, for each kind of entity, could we add "location" information, e.g., the file, line, and column at which the declaration occurs?
>>
>> Added "line" and "column" attributes to the root tag.
>
> Could we get the full pathname as well?

Done.

> Thanks, patch LGTM!

Thank you for the review!  Committed r161431.

Dmitri

-- 
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr at gmail.com>*/