修改Xcode自动生成的文件注释来导出API文档
![](https://i-blog.csdnimg.cn/blog_migrate/a6e04c1e2aa007fa7d46b8694e50da69.webp?x-image-process=image/format,png)
先上文档效果图
![](https://i-blog.csdnimg.cn/blog_migrate/95ee56dbe3f308b9fe3b26199da3ddd5.webp?x-image-process=image/format,png)
![](https://i-blog.csdnimg.cn/blog_migrate/a7769e0b4907d9c2941cd7b54939fc43.webp?x-image-process=image/format,png)
![](https://i-blog.csdnimg.cn/blog_migrate/b0a7b183a47811462f7d747fb04d7440.webp?x-image-process=image/format,png)
- 导出注释标准
/*! 头文件基本信息。这个用在每个源代码文件的头文件的最开头。
@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
到了这个目录下,是不是觉得子目录的名字有些熟悉呢?
![](https://i-blog.csdnimg.cn/blog_migrate/414b75819b84727679df4cf5024c16a8.webp?x-image-process=image/format,png)
![](https://i-blog.csdnimg.cn/blog_migrate/00ef67cce229390487d931c28ba2bcb8.webp?x-image-process=image/format,png)
选中Source -> Cocoa Touch Class.xctemplate
这个目录下面有很多后缀名为Objective-C跟Swift的文件夹,这么多怎么看呢?我们先打开NSObjectObjective-C下面的___FILEBASENAME___
![](https://i-blog.csdnimg.cn/blog_migrate/dba00e2c51a86f25e9e7dbd8b9c3eac4.webp?x-image-process=image/format,png)
上面那绿油油的注释就是我们要修改的东西了,注意它的格式,跟我们创建文件的头部注释是一样的
![](https://i-blog.csdnimg.cn/blog_migrate/a924b13a4f82ecc608bfc4755bbebc17.webp?x-image-process=image/format,png)
这里用到了几个系统的预处理宏定义,包括__FILENAME__、__PROJECTNAME__、__FULLUSERNAME__、__DATE__和__COPYRIGHT__,分别表示的是文件名、项目名称、系统用户全称、当前日期和版权声明,这些宏定义可以用在我们修改之后的注释中。我把它修改成下面这样:
![](https://i-blog.csdnimg.cn/blog_migrate/f940830108203e05613eebefe86ef1e2.webp?x-image-process=image/format,png)
退出Xcode重新运行,然后创建新类,我们就会发现新的类文件格式:
![](https://i-blog.csdnimg.cn/blog_migrate/9150e22c01cfe7baf66fc177480a0564.webp?x-image-process=image/format,png)
这样我们需要的头文件注释文档已经自动生成了,而且是一次操作,永久受益。大家可以如法炮制,在@interface的注释模板上加上规范类信息的注释文档,就可以直接创建类的注释文档。
- 如何导出文档
修改好了Xcode的自动生成注释格式,接下来就是最重要的导出API文档操作。首先在选择项目,然后add new target -> Other -> aggregate -> 命名 -> 创建完毕
![](https://i-blog.csdnimg.cn/blog_migrate/88282ce09e67c1f097bac2d796ef2de7.webp?x-image-process=image/format,png)
选择新创建好的target -> add New Run Script Phase
![](https://i-blog.csdnimg.cn/blog_migrate/b1f9f7b52575e7f345e8295992b6bb3f.webp?x-image-process=image/format,png)
在建好的run script中填写下面的信息
# shell script goes here
mkdir -p headerDoc
find (这里填写导出文档的绝对路径) \*.h -print | xargs headerdoc2html -o headerDoc
gatherheaderdoc headerDoc
exit 0
![](https://i-blog.csdnimg.cn/blog_migrate/a7feedd4b12c25dc0033f57cde7b2edd.webp?x-image-process=image/format,png)
选择使用新建的target运行
![](https://i-blog.csdnimg.cn/blog_migrate/24e944af8ef6c79d51e254b3b7cb78d8.webp?x-image-process=image/format,png)
然后运行成功后到填写的路径下就可以看到导出的API文档文件夹