使用appledoc 生成技术API文档具体解释

一、首先安装 appledoc

第一步：使用终端命令进行下载安装
```
git clone git://github.com/tomaz/appledoc.git

cd ./appledoc

sudo sh install-appledoc.sh
```
上面步骤运行之后。上面三个步骤都是正常运行的。文件有点大，下载会慢一点，我们看下效果图：

成功安装之后的图片

假设出现 INSTALL SUCCEEDED 则说明我们成功安装了。

以下进行第二步：安装之后我们进行一个简单的验证
```
appledoc --version

//用法能够输入命令

appledoc --help
```
二、用法
第一步：使用终端进入代码文件夹：
1. 直接拖拽我们的project到终端，然后回车一下
2. 或者使用 cd+"项目名字文件夹" 同1
3. 以上两种方法都能够进入到我们的project根文件夹
第二部：

project-name: 项目名字

project-company: 公司名称

使用命令：

//以下这个会运行错误

1. appledoc --project-name 你的工程名字 --project-company 公司名 ./(导出路径，这里是指根文件夹)  path所要导出的文档的类文件夹

错误提示是：AppledocException: At least one directory or file name path is required

2. 正确的运行命令：

appledoc --no-create-docset --output ~/doc --project-name "Your Project Name" --company-id "com.yourcommpany" --project-company "Your Company"  ./

3. appledoc --project-name DiskSizeDemo

         --project-company "ray"

         --company-id aaaa

         --output ./apple

~/DeskTop/RYDemoTest/DiskSizeDemo/DiskSizeDemo/doc/

        最后一个命令须要5个參数：

       1. 工程名字

       2. 公司名字

       3. 公司ID

       4. 生成结果出书路径

       5. 扫描那个路径下的类

运行成功都能够在我们对应的地址下找到

4. appledoc -o ./doc --project-name DiskSizeDemo --project-company feel .

appledoc会扫描当前路径下的全部文件，然后生成好文档放到doc文件夹下。你也能够用appledoc –help查看全部可用的參数。

使用的时候一定要注意最后一个路径。别忘了。不然会提示错误。最后一个是导出扫描到的文件

上面执行成功会出现以下截图

imageMogr2/auto-orient/strip%7CimageView2/2/w/1240" class="imagebubble-image" alt="">

我们能够在电脑的 Users 下找到raybon 这个目录

project中使用
1. 我们先新建一个project，Demo 就是我们实验的測试DiskSizeDemo
2. 选择菜单File->New File -> Target ：

这里都能看懂吧

加入之后我们在去设置界面

imageMogr2/auto-orient/strip%7CimageView2/2/w/1240" class="imagebubble-image" alt="">

QQ20160317-2@2x.png

通过我们新添加的Run Script

加入一下脚本

#appledoc Xcode script

# Start constants

company="abc";

companyID="com.abc";

companyURL="http://abc.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}"

然后选择以下

QQ20160317-3@2x.png

选择好之后我们run 一下

project中我们新建的有个Doc.h 和Doc.m 的类

代码例如以下

#import <Foundation/Foundation.h>

@interface Doc : NSObject

/*! @brief this is comment.  */

- (void)run;

/*!  @brief查询数据方法 */

- (void)seekMethod;

@end

我们假设run 之后能够在本地找到一个 dorset-install.txt 文件

imageMogr2/auto-orient/strip%7CimageView2/2/w/1240" class="imagebubble-image" alt="">

QQ20160317-4@2x.png

我们打开HTML 下的index.html

QQ20160317-5@2x.png

看到了吧，是不是我们常常看到的技术文档

我们假设想要导出这样的格式，凝视须要依照规定的来，这个我不清楚为什么要这样子，有知道的还望留言一下。在此谢过大神。

我去查询的资料是支持一下三种凝视格式：

1. /*!  this a test . */

2. /**  this a comment. */

3. /// this is a long comment. */

常常使用的标签：

@brief : 使用它来写一段你正在文档化的method, PRoperty, class, file, struct, 或enum的短描写叙述信息。

@discusstion: 用它来写一段详尽的描写叙述。假设须要你能够加入换行。

@param:通过它你能够描写叙述一个 method 或 function的參数信息。你能够使用多个这样的标签。

@return: 用它来制定一个 method 或 function的返回值。

@see: 用它来指明其它相关的 method 或 function。你能够使用多个这样的标签。

@sa:同上

@code ： 使用这个标签，你能够在文档其中嵌入代码段。

当在Help Inspector其中查看文档时，代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用@endcode标签。

@remark : 在写文档时，用它来强调不论什么关于代码的特殊之处。

举例：

/*! @brief This property knows my name. */

@property (nonatomic, strong) NSString *myName;

这样的凝视在调用的时候也会有提示，我们如今经常使用的VVDocument-Xcode 凝视插件，是一样的原理

记录文件经常使用标签：

让我介绍一些当你在记录一个文件时会用到的新标签：

@file: 使用这个标签来指出你正在记录一个文件（header 文件或不是）。

假设你将使用Doxygen来输出文档。那么你最好在这个标签后面紧接着写上文件名称字。

它是一个top level 标签。

@header: 跟上面的类似，可是是在 HeaderDoc中使用。当你不使用 Doxygen时。不要使用上面的标签。

@author：用它来写下这个文件的创建者信息

@copyright: 加入版权信息

@version: 用它来写下这个文件的当前版本号。假设在project生命周期中版本号信息有影响时这会非常重要。

再一次的，我仅仅给出最经常使用的标签。自己查看说明文档了解很多其他标签信息。

@class: 用它来指定一个class的凝视文档块的开头。

它是一个top level标签，在它后面应该给出class名字。

@interface: 同上

@protocol: 同上两个一样。仅仅是针对protocols

@superclass: 当前class的superclass

@classdesign: 用这个标签来指出你为当前class使用的不论什么特殊设计模式（比如，你能够提到这个class是不是单例模式或者类似其他的模式）。

@coclass: 与当前class合作的另外一个class的名字。

@helps: 当前class帮助的class的名字。

@helper: 帮助当前class的class名字。

使用HeaderDoc生成文档

到此我们就结束了，详细其它使用也能够參考以下这个

headerdoc2html

Xocde 高速生成文档

 官方使用;

查询生成的HTML页面：

~/Library/Developer/Shared/Documentation/DocSets/

本文主要使用了appledoc

其次就是 headerdoc ,我測试了两种，仅仅是认为appledoc 的更好一些。看着界面更舒服一些。

文／Raybon_lee（简书作者）

原文链接：http://www.jianshu.com/p/65f1afdb9445

著作权归作者全部，转载请联系作者获得授权，并标注“简书作者”。

使用appledoc 生成技术API文档具体解释

一、 首先安装 appledoc

二、用法

一、首先安装 appledoc