简介
AppleDoc可以根据项目中的注释自动生成类似于Apple官方文档的文档文件,大致的效果类似于这样:
![](https://img.haomeiwen.com/i1677656/3fc162c84b38a3b2.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
![](https://img.haomeiwen.com/i1677656/87e38aa181e9516d.png)
![](https://img.haomeiwen.com/i1677656/cf5446b0ae32baa0.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}"`
![](https://img.haomeiwen.com/i1677656/6d5c511c76669b2e.png)
4.3 编译新建的文档target
就会在outputPath路径下生成对应的docset文档
Xcode9之后,普遍的方法会出现此错误,但是文档已经生成了,具体原因还要查看资料:
unable to find utility "docsetutil", not a developer tool or in PATH
网友评论