修改Xcode自动生成的文件注释来导出API文档

最近工作需要和其他公司进行项目交接的时候，原以为像往常一样直接交付源代码就行了，谁知道客户公司需要我们提供API文档。瞬间我和小伙伴们都惊呆了，什么鬼！从来没做过。后来看了一下安卓组提供的API文档发现是HTML格式的类文件注释介绍，于是残酷的打消了我想手动编写API文档的想法。

抱着这样的想法在网上搜索了蛮久，总算是找到了Xcode自带的导出API文档的方法。但作为崇拜猫神的一员的我，使用的是猫神的VVDocumenter插件，惊讶的发现这个插件生成的注释并不能支持导出正确的文档。于是只好苦逼的加班加点把整个项目的注释统统修改了一遍，最近在简书上看到小码哥的一篇修改Xcode自动生成的文件注释的文章，于是想到了结合这种方法来减轻我们导出文档的难度。这里并不是说第三方插件生成的注释不好，但是对于有相同需求的码农们可以参考我的这篇文章。废话少说，先上文档效果图

- 导出注释标准

/*!  头文件基本信息。这个用在每个源代码文件的头文件的最开头。

@header 这里的信息应该与该源代码文件的名字一致

@abstract 关于这个源代码文件的一些基本描述

@author Sindri Lin (作者信息)

@version 1.00 2012/01/20 Creation (此文档的版本信息)

*/

/*!  类信息。此注释用在类声明的开头。

@class

@abstract 这里可以写关于这个类的一些描述。

*/

/*!

@property  property的相关注释。

@abstract 这里可以写关于这个Property的一些基本描述。

*/

/*!

@method  函数(方法)的相关注释。

@abstract 这里可以写一些关于这个方法的一些简要描述

@discussion 这里可以具体写写这个方法如何使用，注意点之类的。如果你是设计一个抽象类或者一个共通类给给其他类继承的话，建议在这里具体描述一下怎样使用这个方法。

@param text 文字 (这里把这个方法需要的参数列出来)

@param error 错误参照

@result 返回结果

*/

/*!

@enum  enum的相关注释。

@abstract 关于这个enum的一些基本信息

@constant HelloDocEnumDocDemoTagNumberPopupView PopupView的Tag

@constant HelloDocEnumDocDemoTagNumberOKButton OK按钮的Tag

*/

/*!

@category  category的相关注释。

@abstract NSString的Category

*/

/*!

@protocol  protocol的相关注释

@abstract 这个HelloDoc类的一个protocol

@discussion 具体描述信息可以写在这里

*/

上面的注释很明显跟我们平时的注释不一样，如果要严格按照这个格式进行注释，估计要累死一群码农。但是，上面的头文件、类声明和类别声明我们都能通过修改Xcode本身的设置来实现创建文件时就将注释文档设置完毕。

- 修改Xcode自身生成的文件注释

首先右键Xcode -> 选项 -> 在Finder中打开 -> 右键 -> 显示包内容

Contents -> Developer -> Platforms -> iPhoneOS.platform -> Developer -> Library -> Xcode -> Templates -> File Templates

到了这个目录下，是不是觉得子目录的名字有些熟悉呢？

选中Source -> Cocoa Touch Class.xctemplate

这个目录下面有很多后缀名为Objective-C跟Swift的文件夹，这么多怎么看呢？我们先打开NSObjectObjective-C下面的___FILEBASENAME___

上面那绿油油的注释就是我们要修改的东西了，注意它的格式，跟我们创建文件的头部注释是一样的

这里用到了几个系统的预处理宏定义，包括__FILENAME__、__PROJECTNAME__、__FULLUSERNAME__、__DATE__和__COPYRIGHT__，分别表示的是文件名、项目名称、系统用户全称、当前日期和版权声明，这些宏定义可以用在我们修改之后的注释中。我把它修改成下面这样：

退出Xcode重新运行，然后创建新类，我们就会发现新的类文件格式：

这样我们需要的头文件注释文档已经自动生成了，而且是一次操作，永久受益。大家可以如法炮制，在@interface的注释模板上加上规范类信息的注释文档，就可以直接创建类的注释文档。

- 如何导出文档

修改好了Xcode的自动生成注释格式，接下来就是最重要的导出API文档操作。首先在选择项目，然后add new target -> Other -> aggregate -> 命名 -> 创建完毕

选择新创建好的target -> add New Run Script Phase

在建好的run script中填写下面的信息

# shell script goes here

mkdir -p headerDoc

find (这里填写导出文档的绝对路径) \*.h -print | xargs headerdoc2html -o headerDoc

gatherheaderdoc headerDoc

exit 0

选择使用新建的target运行

然后运行成功后到填写的路径下就可以看到导出的API文档文件夹

学会导出API文档无疑可以极大的提高我们的代码的可读性，而在很多重要的场合下，代码的可读性甚至要高于代码的质量。因此，成为一名优秀的程序员也要能够自觉规范自己的代码注释规范，来为随时的导出文档做好准备。代码之路漫漫，且行且珍惜

开发日记

转载请注明：http://www.jianshu.com/p/d0c7d9040c93