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

[Jordan Rose]

On Aug 6, 2012, at 23:04 , Douglas Gregor <dgregor at apple.com> wrote:

>>> I think the comment XML format looks great; it's a good balance between simplicity for the client and capability for rendering documentation comments. Some nitpicks follow:
>>> 
>>> +  <start>
>>> +    <choice>
>>> +      <ref name="Function" />
>>> +      <ref name="Class" />
>>> +      <ref name="Variable" />
>>> +      <ref name="Namespace" />
>>> +      <ref name="Typedef" />
>>> +    </choice>
>>> +  </start>
>>> 
>>> I understand that the set of choices is intentionally limited, to simplify the output, but it looks like we're missing some necessary categories: enumeration types, (Objective-C) protocols, (Objective-C) categories and (Objective-C) properties, at a minimum. Should there still be an "other" category here?
>> 
>> 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.


FWIW, the docs on developer.apple.com put categories in with classes (the "Additions"), except for what are called "informal protocols", which were categories on NSObject meant to behave kind of like @optional. I think it's okay not to handle the latter.

http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/_index.html

As for properties, they are usually included with methods rather than variables in Apple's docs.

http://developer.apple.com/library/ios/#DOCUMENTATION/GraphicsImaging/Reference/CAAnimation_class/Introduction/Introduction.html#//apple_ref/occ/cl/CAAnimation


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/cfe-commits/attachments/20120807/5279b1e8/attachment.html>