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 中前往文件夹。