Question

问题：
应该在示例SCParserDelegate Protocol中为每个方法编写一份文档注释。

背景：
我正在构建一个供第三方开发人员使用的解析框架。（这是我的第一个框架项目，因此我的开发过程是高度学术化以最大化学习。）

示例代码：

/** @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很痛苦。想想你浪费了多少时间按＆＃39; *＆＃39;或＆＃39; /＆＃39;，然后反复输入参数。现在，您可以找到要记录的方法（或任何代码），以及键入///，将为您和所有参数生成文档 return将被提取为兼容的Javadoc样式与appledoc，Doxygen和HeaderDoc。你可以填写内联占位符令牌可以完成您的文档。

Answer 2

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。 VVD文件管理器非常有用，所以我建议安装它。

内联文档对Objective-C协议及其方法的评论＆amp;属性

2 个答案: