| title | author | category | translator | excerpt |
|---|---|---|---|---|
Documentation |
Mattt |
Objective-C |
April Peng |
Cocoa 开发者间流传着一句格言，Objective-C 的冗长使得其代码就是有效的自我说明。有了 longMethodNamesWithNamedParameters: 以及参数的显式类型，Objective-C 的方法不会给人留下太多的想象空间。 |
Cocoa 开发者间流传着一句格言，Objective-C 的冗长使得其代码就是有效的自我说明。有了 longMethodNamesWithNamedParameters: 以及参数的显式类型，Objective-C 的方法不会给人留下太多的想象空间。
但即使是自我说明的代码也可以通过说明文档加以改进，而且只需少量的努力就可以给别人产生显著的好处。
听着 - 我知道程序员不喜欢被告知该怎么做，“你应该” 和 “你不该” 的规范性论证有长号的修辞影响，所以我就切入正题：
你喜欢苹果的文档吗？难道你不希望为自己的库也编写同样的文档吗？只需几个简单的步骤，你的代码就可以得到它该有的文档。
每一个现代编程语言都有注释：由一个特殊的字符序列标记的非可执行的自然语言，如 //，/**/，＃ 和 --。使用特殊格式注释的文档，提供了代码的辅助解释和上下文，可以用编译工具提取和解析。
在 Objective-C，可选的文档工具是 appledoc。使用类似 Javadoc 的语法，appledoc 能够从 .h 文件生成 HTML 和 Xcode 兼容的 .docset 文档，外观和苹果官方文档 几乎相同 .
Doxygen，主要用于 C++，是 Objective-C 的另一种可行选择，但一般在 iOS / OS X 的开发者社区不很受待见。
下面是一些文档化很好的 Objective-C 项目的例子：
Objective-C 的文档是由 /** */ 标记的注释块（注意额外的初始星号），先于任何 @interface 或 @protocol，以及任何方法或 @property 声明。
对于类，类别和协议，文档应说明该特定组件的用途，提供应该如何使用的建议和指导。将它构造的像一个新闻报道：先从顶层“一篇微博大小的”概述，然后在必要的地方更详细的做进一步探讨。关注一个类为何应该（或不应该）被继承，或标准协议（比如 NSCopying）的任何行为警告都应始终做好记录。
每个方法都应该以一个简要的开始来说明其功能，接着是任何警告或其他详细信息。方法文档中还含有 Javadoc 风格的 @ 标签来标识诸如参数和返回值这样的常有字段：
@param [参数] [说明]：描述此参数应该传递什么样的值@return [说明]：描述方法的返回值@see [selector]：提供相关方法的“另见”引用@warning [说明]：标识出异常或潜在的危险行为
属性往往被描述在一个简单的句子里，并且应该包括它的默认值。
相关的属性和方法应该由一个 @name 声明来分组，类似于一个#pragma mark 的功能，并且可以与三重斜线（///）的注释类型一起使用。
在编写你自己的文档前试着阅读一些其他的文档，这样才能得到正确的基调和风格的认知。当对术语或冗长的描述有质疑的时候，你可以遵循从苹果的官方文档能找到的最接近的文档模式。
为了帮助加快项目文档编写的过程，你可能要看看 VVDocumenter-Xcode 项目，该项目会根据自己的签名为方法自动添加
@param和@return标签。
只需按照这些简单的指导，你就可以给自己的项目添加精美的，内容丰富的文档。一旦你找到了它的窍门，你会发现文档很快就生成了。
谢谢 @orta 对这周话题的建议, 他正在进行的 CocoaDocs 项目可以为那些在 CocoaPods 发布的项目自动生成文档。