[ios]利用xcode自动生成项目文档

转自：http://blog.csdn.net/linqir/article/details/8086974

 

在写代码的时候，如果按照一定的规范在头文件里写上注释的话，

就可以利用Xcode的文档自动输出功能生成一份完整的HTML项目文档。

生成的格式和Apple Developer网站上的API文档几乎是一样的。

我们来看看如何利用Xcode生成项目文档。
步骤:
1. 在XCode里点击Project,然后点Add Target给项目添加一个TARGET

2. 在添加Target的弹出对话框里，选择Aggregate,点击Next,输入一个你喜欢的名字,点击Finish

3. 你会发现TARGETS下面多了一个项目，点击它，然后在右边点击BuildPhases标签，然后点击Add Build Phase并选择Add Run Script

4. Run Script添加成功后，点击它的下拉菜单，把以下代码拷贝到代码对话框里。

# shell script goes here

mkdir -p headerDoc

find ./HelloPhoneGap/Classes -name \*.h -print | xargs headerdoc2html -o headerDoc

gatherheaderdoc headerDoc

exit 0
注意：代码里的./HelloPhoneGap/Classes是你的类文件的保存的路径，请根据各自情况修改。

5. 在XCode左上角的Scheme里选定刚才生成的Target,然后点Run。
运行以后，在你的项目文件夹里，就会生成一个文档文件夹了。
这些自动生成的文档都是根据你在源代码里写的注释生成的。

 

下面就详细介绍一下各种能自动生成文档的注释
■ header : 头文件基本信息。这个用在每个源代码文件的头文件的最开头。
例如:

/*!
@header 这里的信息应该与该源代码文件的名字一致
@abstract 关于这个源代码文件的一些基本描述
@author Kevin Wu (作者信息)
@version 1.00 2012/01/20 Creation (此文档的版本信息)
*/

■ class: 类信息。此注释用在类声明的开头。
例如:

/*!
@class
@abstract 这里可以写关于这个类的一些描述。
*/
@interface MyClass : NSObject {
}

■ property: property的相关注释。

/*!
@property
@abstract 这里可以写关于这个Property的一些基本描述。
*/
@property (nonatomic,readonly) NSString *helloDocText_;

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

/*!
@method
@abstract 这里可以写一些关于这个方法的一些简要描述
@discussion 这里可以具体写写这个方法如何使用，注意点之类的。如果你是设计一个抽象类或者一个
共通类给给其他类继承的话，建议在这里具体描述一下怎样使用这个方法。
@param text 文字 (这里把这个方法需要的参数列出来)
@param error 错误参照
@result 返回结果
*/
- (BOOL)showText:(NSString *)text
error:(NSError **)error;

■ enum: enum的相关注释。

/*!
@enum
@abstract 关于这个enum的一些基本信息
@constant HelloDocEnumDocDemoTagNumberPopupView PopupView的Tag
@constant HelloDocEnumDocDemoTagNumberOKButton OK按钮的Tag
*/
typedef enum HelloDocEnumDocDemo_{
HelloDocEnumDocDemoTagNumberPopupView = 100,
HelloDocEnumDocDemoTagNumberOKButton,
}HelloDocEnumDocDemo;

■ category: category的相关注释。

/*!
@category
@abstract NSString的Category
*/
@interface KevinNSString (NSString)

■ protocol: protocol的相关注释

/*!
@protocol
@abstract 这个HelloDoc类的一个protocol
@discussion 具体描述信息可以写在这里
*/
@protocol HelloDocDelegate ＜NSObject＞

以上列举的标准注释也许并不完善。
具体请参考苹果的developer网站的API文档。
以上列举的标准注释全都在下面的头文件里，仅供参考。

评论

1 楼 wangyudong 2017-11-27  

很多API doc生成工具生成doc需要重度依赖代码里加注解的方式，并且不支持自动化测试RESTful API。

之前习惯用一款名字为 WisdomTool REST Client，它能够基于测试过的历史记录自动生成精美的RESTful API文档，完全不用在代码里加注解，支持自动化测试RESTful API，输出精美的测试报告。
轻量级的工具，功能却很精悍哦！

https://github.com/wisdomtool/rest-client

Most of API doc tools do not support automated testing.

Once used a tool called WisdomTool REST Client supports automatically generating exquisite RESTful API documentation based on history testing cases without adding annotations to the code, it also supports automated testing, and outputs exquisite report.

Lightweight tool with very powerful features!

https://github.com/wisdomtool/rest-client