iOS使用appledoc 生成技术API文档详解

一、 首先安装 appledoc

Update: 最近版本更新 需要解决的同学看这里
问题： 安装完成提示下面的错误的同学看一下连接，其他正常的不需要查看
install: /tmp/Build/Intermediates/ArchiveIntermediates/appledoc/InstallationBuildProductsLocation/usr/local/bin/appledoc: No such file or directory

https://github.com/tomaz/appledoc/issues/588
https://github.com/tomaz/appledoc/pull/526

• 第一步：使用终端命令进行下载安装

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

上面步骤执行之后，上面三个步骤都是正常执行的，文件有点大，下载会慢一点，我们看下效果图：

如果出现 ** INSTALL SUCCEEDED ** 则说明我们安装成功了。

• 下面进行第二步：安装之后我们进行一个简单的验证

appledoc --version
//使用方法可以输入命令
appledoc --help

二、使用方法

• 第一步：使用终端进入代码目录：
  1. 直接拖拽我们的工程到终端，然后回车一下
  2. 或者使用 cd+"项目名字目录" 同1
  3. 以上两种方法都可以进入到我们的工程根目录
• 第二部：
  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查看所有可用的参数。
使用的时候一定要注意最后一个路径，别忘了，不然会提示错误，最后一个是导出扫描到的文件

上面运行成功会出现下面截图

我们可以在 电脑的 Users 下找到raybon 这个文件夹

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

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

通过我们新增加的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}"

然后选择下面

选择好之后我们run 一下
工程中我们新建的有个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 文件

我们打开HTML 下的index.html

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

我们如果想要导出这种格式，注释需要按照规定的来，这个我不清楚为什么要这样子，有知道的还望留言一下，在此谢过大神。

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

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: 用它来写下这个文件的当前版本。如果在工程生命周期中版本信息有影响时这会很重要。

再一次的，我只给出最常用的标签。自己查看说明文档了解更多标签信息。

@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 的更好一些，看着界面更舒服一些。