目标 C @property 注释答案

【问题标题】：Objective C @property comments目标 C @property 注释
【发布时间】：2011-01-23 20:08:52
【问题描述】：

我使用 Doxygen 为我的目标 c 代码生成文档。到目前为止，我还没有找到任何关于如何正确记录属性的指南。我看过的例子是尽一切可能做到的。有些人自己记录变量，有些人记录@property 声明。一些使用 //，而另一些使用完整的 /** */ 块。

谁能给我指出最佳实践的参考？或者也许是一些关于未来与 Doxygen 兼容性的信息？我想坚持一种模式，至少，一旦他们开发出官方模式，就很容易适应 Doxygen。

【问题讨论】：

【解决方案1】：

我只能说Core Plot framework 在实现中使用如下格式注释属性声明

 /** @property myProperty
 *   @brief Property is very useful
 *   Useful and there is a lot more to tell about this property **/

它似乎使用 Doxygen 生成了干净的文档。来自Core Plot documentation policy：

@property 是 doxygen 所必需的找不到属性名称否则。

只读访问器属性，复制/保留/分配，非原子是自动添加，不应该发生在手册部分文档。

【讨论】：

【解决方案2】：

您可以在此处找到有关 Objective-C 编码约定的一些信息：Google Objective-C Style Guide

但是如果你愿意，还有一个叫做 HeaderDoc 的好软件可以在 XCode 下生成文档。你可以在这里查看它的编码风格：HeaderDoc Tags

【讨论】：

有用的参考资料，我投了赞成票，但并没有真正回答我的任何问题。 google doc 省略了@property 评论的任何准则，headerdoc 当然是一种替代方案，但对我来说不是解决方案。

【解决方案3】：

我的经验是：

当我在 cmets 中使用 @property 标记时，属性的 doxygen 输出会损坏，例如：[ClassName]:[read, write, assign]。

如果我省略 @property 标记，而是依靠 doxygen 在源代码中的注释块下方找到“@property”声明，一切正常。

相比之下，@interface 适用于接口，@protocol 适用于协议。

另外，在过去，我在一些协议声明中使用了 doxygen 'slip'。 Obj-C 还是二等的 doxygen 公民吗？

注意：我在 Mac 上使用 GUI/向导，注释块使用 '/**!'而不是 '/**'。

【讨论】：