Objective-C 协议及其方法和属性的内联文档注释

Question

问题：
应该为示例 SCParserDelegate 协议中的每个方法编写文档注释。

上下文：
我正在构建一个供第 3 方开发人员使用的解析框架。 （这是我的第一个框架项目，所以我的开发过程是高度学术性的，以最大限度地学习。）

示例代码：

/** @protocol SCParserDelegate
 *   @brief Protocol for a Delegate to handle Callbacks when an SCParser finds Tags
 */
@protocol SCParserDelegate
@required
@property (readonly) BOOL processing;
@optional
-(void)parserDidStart:(SCParser *)parser;
-(void)parserDidFinish:(SCParser *)parser;
-(void)parser:(SCParser *)parser didOpenTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser didCloseTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser didSingleTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser whitelistDeniedTag:(SCTag *)tag;
-(void)parser:(SCParser *)parser parseErrorOccurred:(NSError *)parseError;
-(void)parser:(SCParser *)parser foundCharacters:(NSString *)content;
@end

问题：
如何在上面的示例代码中为每个方法和属性手动编写自己的文档注释块？

Answer 1

听起来您想使用VVDocumenter 之类的东西。

来自他们的 Github 页面：

编写文档对于开发来说非常重要，但它真的很重要 Xcode 很痛苦。想想你浪费了多少时间 按“*”或“/”，然后一次又一次地键入参数。现在， 您可以找到要记录的方法（或任何代码），并且 输入///，将为您和所有参数生成文档和 return 会被提取成 Javadoc 风格，兼容 与 appledoc、Doxygen 和 HeaderDoc。你可以只填写内联 占位符标记来完成您的文档。

Answer 2

NSHipster 在这方面有很好的 cmets。 http://nshipster.com/documentation/

至于委托，最好通知符合协议的人何时发送消息，例如：

/*!
 * @field processing   Flag indicating that the operation is currently in process
 */
@property (readonly) BOOL processing;

/*!
 * Sent right after the parser began
 * 
 * @param parser (Something about the parser)
 */
-(void)parserDidStart:(SCParser *)parser;

/*!
 * Sent after the parser opens the given tag (maybe some hints as to what the delegate may do)
 *
 * @param parser (Words about the parser)
 * @param tag    (Something about the tag)
 */
-(void)parser:(SCParser *)parser didOpenTag:(SCTag *)tag;

还有其他有用的标签，例如@return 和@warning。 VVDocumenter 非常有用，所以我建议安装它。