On Aug 6, 2012, at 23:04 , Douglas Gregor <[email protected]> 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
_______________________________________________ cfe-commits mailing list [email protected] http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
