<html><head><meta http-equiv="Content-Type" content="text/html charset=windows-1252"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><br><div><div>On Aug 6, 2012, at 23:04 , Douglas Gregor <<a href="mailto:dgregor@apple.com">dgregor@apple.com</a>> wrote:</div><br class="Apple-interchange-newline"><blockquote type="cite"><blockquote type="cite" style="font-family: monospace; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><blockquote type="cite">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:<br><br>+ <start><br>+ <choice><br>+ <ref name="Function" /><br>+ <ref name="Class" /><br>+ <ref name="Variable" /><br>+ <ref name="Namespace" /><br>+ <ref name="Typedef" /><br>+ </choice><br>+ </start><br><br>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?<br></blockquote><br>Yes, I will add 'Other' for now, but at least 'Enum' should be added<br>separately. I think Protocols and categories can be handled as<br>'Class'es, properties -- as 'Variables'. Of course, unless we want to<br>store additional information for these.<br></blockquote><br style="font-family: monospace; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "><span style="font-family: monospace; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; display: inline !important; float: none; ">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.</span><br style="font-family: monospace; font-size: medium; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; line-height: normal; orphans: 2; text-align: -webkit-auto; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px; "></blockquote></div><br><div><br></div><div>FWIW, the docs on <a href="http://developer.apple.com">developer.apple.com</a> put categories in with classes (the "Additions"), <i>except</i> 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.</div><div><br></div><div><a href="http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/_index.html">http://developer.apple.com/library/mac/#documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/_index.html</a></div><div><br></div><div>As for properties, they are usually included with methods rather than variables in Apple's docs.</div><div><br></div><div><a href="http://developer.apple.com/library/ios/#DOCUMENTATION/GraphicsImaging/Reference/CAAnimation_class/Introduction/Introduction.html#//apple_ref/occ/cl/CAAnimation">http://developer.apple.com/library/ios/#DOCUMENTATION/GraphicsImaging/Reference/CAAnimation_class/Introduction/Introduction.html#//apple_ref/occ/cl/CAAnimation</a></div><div><br></div><div><br></div></body></html>