appledoc

简介

AppleDoc可以根据项目中的注释自动生成类似于Apple官方文档的文档文件，大致的效果类似于这样：

image.png

AppleDoc还是有一些限制的，就是要在代码中加上注释，而且只支持/**/、///、//等格式，不支持#pragma mark - WKNavigationDelegate。

appdoc支持的注释：

`/// 这是单行注释。`

`/** 这也是单行注释 */`

`/*! 同样是单行注释 */`

`/** 这也是单行注释，`

`*  第二行会接上第一行。`

`*/`

`/** 第一行是类的简介`

`在简介的下面,就是类的详细介绍了。`

`没有间隔换行会被消除，就像Html那样。`

`下面是常用的markdown语法`

`- - -`

`无序列表: (每行以 '*'、'-'、'+' 开头):`

`* this is the first line`

`* this is the second line`

`* this is the third line`

`有序列表: (每行以 1.2.3、a.b.c 开头):`

`a. this is the first line`

`b. this is the secode line`

`多级列表:`

`* this is the first line`

`a. this is line a`

`b. this is line b`

`* this is the second line`

`1. this in line 1`

`2. this is line 2`

`标题:`

`# This is an H1`

`## This is an H2`

`### This is an H3`

`#### This is an h4`

`##### This is an h5`

`###### This is an H6`

`链接:`

`普通URL直接写上，appledoc会自动翻译成链接: [http://    blog.ibireme.com](http://    blog.ibireme.com)`

`[这个]([http://example.net/](http://example.net/)) 链接会隐藏实际URL.`

`表格:`

`| header1 | header2 | header3 |`

`|---------|:-------:|--------:|`

`| normal  |  center |  right  |`

`| cell    | cell    | cell    |`

`引用:`

`这里会引用到方法 `someMethod:`，这里会引用到类 `YYColor``

`这里会引用到一个代码块`

`void CMYK2RGB(float c, float m, float y, float k, `

`float *r, float *g, float *b) {`

`*r = (1 - c) * (1 - k);`

`*g = (1 - m) * (1 - k);`

`*b = (1 - y) * (1 - k);`

`}`

`@since iOS5.0`

`*/`

`@interface AppledocExample : NSObject`

`///这里是属性的说明`

`@property (nonatomic, strong) NSString *name;`

`/** `

`@brief 这里是方法的简介。该Tag不能放到类注释里。`

`@exception UIColorException 这里是方法抛出异常的说明`

`@see YYColor`

`@see someMethod:`

`@warning 这里是警告，会显示成蓝色的框框`

`@bug 这里是bug，会显示成黄色的框框`

`@param red   这里是参数说明1`

`@param green 这里是参数说明2`

`@param blue   这里是参数说明3`

`@return  这里是返回值说明`

`*/`

`- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue;`

`- (void)someMethod:(NSString *)str;`

`@end`

1、安装

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

查看版本
appledoc --version

2、生成doc文件

cd到你的项目文件夹下,执行如下命令：

appledoc --project-name 工程名 --project-company 公司名 ./

3、找到如下文件

执行上面的命令后，会在当前目录下生成如下文件：【文件中存储了生成的docset文件路径】
docset-installed.txt

4、集成到工程中

4.1 新建target

image.png

image.png

4.2 粘贴脚本

将如下脚本代码，按照自己的工程配置后，粘贴到新建的target中的脚本区域【Run Script】

`#appledoc Xcode script  `

`# Start constants  `

`company=``"ACME"``;  `

`companyID=``"com.ACME"``;`

`companyURL=``"[http://ACME.com](http://acme.com/)"``;`

`target=``"iphoneos"``;`

`#target="macosx";`

`outputPath=``"~/help"``;`

`docFilePath=``"/test/test2"``;`

`# 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}/${docFilePath}"`

image.png

4.3 编译新建的文档target

就会在outputPath路径下生成对应的docset文档

Xcode9之后，普遍的方法会出现此错误，但是文档已经生成了，具体原因还要查看资料:
unable to find utility "docsetutil", not a developer tool or in PATH

资料参考：
参考文章1
参考文章2