iOS 自动生成技术文档之 appledoc

安装

• mac终端使用以下命令下载工具源码

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

• 安装成功提示如下

** INSTALL SUCCEEDED **

生成API文档

首先建一个Demo工程名称叫TestAppleDoc

• 终端命令生成

cd xxx/TestAppleDoc
appledoc --project-name 工程名称 --project-company lengyi(公司名称) ./

• 项目工程添加脚本自动生成 （方便更新文档）
  1、选中项目，点击Add Target按钮，选择Cross-platform --> Aggregate
  2、点击Add Build Phase 按钮，添加一个Run Script
  3、添加下面的脚本代码,把前面几行改成自己的
  4、在Xcode左上角选中新建的Target,然后build
  5、文档就会编译好并自动安装进Xcode （每次编译问需要重启Xcode才能看到最新的文档）

#appledoc Xcode script  
# Start constants  
company="lengyi";  
companyID="com.公司id";
companyURL="http://公司网址";
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}"

步骤.png

语法

文档中的注释只有符合规范，才能被appledoc认可，凡是以 "///"、 "/*"、 "/!"开头的注释都算是appledoc注释

/// 这是单行注释。
/** 这也是单行注释 */
/*! 同样是单行注释 */
/** 这也是单行注释，
*  第二行会接上第一行。
*/

例子

DocExample.h

#import <Foundation/Foundation.h>
#import <UIKit/UIKit.h>

@interface DocExample : 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

DocExample.m

#import "docExample.h"

@implementation DocExample

- (UIColor *)initWithRed:(int)red green:(int)green blue:(int)blue{
    UIColor *color = [UIColor colorWithRed:red green:green blue:blue alpha:1];
    return color;
}
- (void)someMethod:(NSString *)str{
    
}

@end

最终效果

效果.png

编译完成后Docset默认会放在
~/Library/Developer/Shared/Documentation/DocSets/路径下
阅读文档
Xcode-->Window-->Documentation And API Reference 找到你的工程名对应的就是文档
或者command+shift+0(零)
编译完成后需要重启Xcode才能看到，如果是初始工程的话，点击了对应文档将会是空白，并且会跳转到脚本写的网址，手动添加注释之后就能看到文档了。

利用Git部署文档

1.拷贝文档

在Git上新建一个仓库,也可以在当前仓库上，将
~/Library/Developer/Shared/Documentation/DocSets/com.公司id.ScanIOSApp.docset/Contents/Resources文件下的html文件拷贝至Git仓库的Master分支然后上传。

2.获取文档访问地址
找到当前仓库，找到Settings，下拉找到并设置如下

CEB36DEB-AB41-43A0-95BF-1EBAD3965D0A.png

3.将该地址添加到README.md中

[文档](https://lengyi.github.io/Doc/)

3.点击如图显示即可解决文档共享的问题。

0E02B8F8-9000-460A-8D64-64E1CA273CC6.png