0

问题：
应该为示例 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


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

4

2 回答 2

2

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

从他们的 Github 页面：

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

于 2014-02-18T18:46:34.007 回答
1

NSHipster 对此有很好的评价。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 很有帮助，所以我建议安装它。

于 2014-02-18T20:19:58.743 回答