xcode文档注释规则简要汇总
参考源
类与协议

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

文本链接

/**
 * - [文档B](DocB) : 类的链接文本.(仅appledoc)
 */

单行注释

///# 标题1
///## 标题2
///hello oc,下面的空行是为了换行
///
///hello swift
/// - 这里使用了无序列表
/// - 使用加粗 **this**, 使用斜体 _this_
/// - 添加一个链接: [百度](http://www.baidu.com)
/// - 添加一个图片:![swift picture](http://img0.imgtn.bdimg.com/it/u=14209024,814391630&fm=21&gp=0.jpg )

多行注释文档

/**
    多行注释文档相比于普通多行注释多了一个星号。
    在这里可以使用markDown语法,书写各种提示信息
    如:显示一个有序列表
    1. 有序列表
    2. 有序列表
    3. 有序列表
*/

方法/函数的注释
方法的注释包括传入参数、返回值、和异常等说明

/**
 初始化 数据和颜色值
 @param frame      frame
 @param dataItems  数据集
 @param colorItems 色值集
 @return self
 */
 - (id)initWithFrame:(CGRect)frame dataItems:(NSArray*)dataItems colorItems:(NSArray*)colorItems;

appledoc使用说明

编译安装:

  • git clone git://github.com/tomaz/appledoc.git
  • cd ./appledoc
  • sudo sh install-appledoc.sh
  • appledoc —version //检查successed

使用

生成HTML

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

appledoc --no-create-docset --output ~/doc --project-name "DrowRect" --company-id "com.jinyuyoulong" --project-company "jinyuyoulong" ./

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

生成docset 此路不通

appledoc --output ./doc --project-name "DrowRect" --project-company "jinyuyoulong" --company-id "com.jinyuyoulong" ./

Xcode脚本生成文档

Xcode 配置

  1. add new target —>选择Other—Aggregate,命名为docText

  2. Build Phases + run script

  3. 编辑run script的内容
  4. 设置target为docText,运行Xcode
  5. 在脚本中标明的导出目录下查看生成的文档

script:

#appledoc Xcode script
# Start constants
company="abc";
companyID="com.abc";
companyURL="http://abc.com";
target="iphoneos";
#target="macosx";
outputPath="~/doc";#输出地址
# 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}"