iOS 代码注释规范

一、注释写法

1.1 注释形式

1.1.1 单行注释

在很多时候只需写一个简要描述就够了，这时最好使用单行注释。推荐格式为

// 简要描述.

1.1.2 多行注释

当需要写详细描述时，这时就需要使用多行注释了。推荐格式为

/** 简要描述.
 *
 * 详细描述或其他.
 */

1.2 类（协议、分类）的注释

对于类（协议、分类）来说，一般只需要写简要描述就行了，这时可以使用单行注释

// 文档A.
@interface DocA : NSObject

当需要留下详细描述时，可换成多行注释

/** 文档B.
 *
 * 文档B的详细描述.
 */
@interface DocB : NSObject

1.3 类 属性的注释

简单的属性用单行注释即可

// 数值属性.
@property (nonatomic,assign) NSInteger num;

当需要留下详细描述时，可换成多行注释

/**
 * @brief 字符串属性.
 *
 * 属性的详细描述.
 */
@property (nonatomic,strong) NSString* str;

1.4 方法的注释

对于没有参数、返回值的简单方法，可以使用单行注释

// 简单方法.
- (void)someMethod;

若方法具有参数或返回值，这时就得使用多行注释了

/**
 * @brief 带整数参数的方法.
 *
 * @param  value 值.
 *
 * @return 返回value.
 */
- (int)someMethodByInt:(int)value;

二、使用appledoc生成文档（docset、html）

2.1 安装appledoc

安装appledoc十分简单。打开终端，输入以下命令

git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh

2.2 使用

首先cd到你的项目文件夹下。

2.2.1 生成doc

appledoc --output ./doc --project-name objcdoc --project-company "zyl910" --company-id "cn.com.zyl910" .

–output ./doc：设置输出目录为“./doc”。
–project-name objcdoc：设置项目名为“objcdoc”。
–project-company “zyl910”：设置公司名为“zyl910”。
–company-id “cn.com.zyl910”：设置公司id为“cn.com.zyl910”。
.：当前目录。

2.2.2 生成html

当需要html文档时，可以加上“–no-create-docset”

appledoc --no-create-docset --output ./doc --project-name objcdoc --project-company "zyl910" --company-id "cn.com.zyl910" ~/Desktop/Test/Test/Helpers

~/Desktop/Test/Test/Helpers : 扫描指定的文件夹目录

当该命令完成后，使用浏览器打开doc/html/index.html

执行命令之后，在你项目的文件夹中会生成一个doc的文件夹。

2.3 将appledoc集成到我们自己的工程中

1、在你的工程中创建新的 Target，注意这里要选择 Other 中的 Aggregate，如图

2、在我们新创建的 Target 中的 Buid Phases 中添加 Run Script

3、打开Run Script，Shell 下面的文档区域添加这样的模板

#appledoc Xcode script  
# Start constants  
company="ACME";  
companyID="com.ACME";
companyURL="http://ACME.com";
target="iphoneos";
#target="macosx";
outputPath="~/help";
# End constants
/usr/local/bin/appledoc \
--project-name "${PROJECT_NAME}" \
--project-company "${company}" \
--company-id "${companyID}" \
--docset-atom-filename "${company}.atom" \
--docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
--docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
--docset-fallback-url "${companyURL}/${company}" \
--output "${outputPath}" \
--publish-docset \
--docset-platform-family "${target}" \
--logformat xcode \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--exit-threshold 2 \
"${PROJECT_DIR}"

4、Xcode 左上方选择这个 Target ，然后 Build 编译。

5、文档就会编译好并且自动安装进 Xcode 了（重启Xcode生效）

6、那么编译之后我们就可以去查看它了，那么在哪里可以看到呢？这时我们就可以用之前生成的 docset-installed.txt文件啦，打开它：看到以一个 Path 了吧：直接复制，然后在 Finder 中前往文件夹。