开源框架：Appledoc——Objective-C文档生成工具使用教程

关于appledoc

---

appledoc是命令行工具，帮助Objective-C 开发者从格式化的源码注释生成像苹果官方风格的文档。
并且可以生成docset文件。

快速安装

---

克隆安装

官方推荐把GitHub的项目clone下来，并在Xcode里编译安装。由于克隆下来的是最新版本，这也是最快的更新方法。打开你的终端并输入下面命令：

git clone git://github.com/tomaz/appledoc.git

这样子会在你的目录下面创建appledoc目录，进入目录你找到appledoc.xcodeproj，打开工程然后编译，这样子就会安装到你的电脑了。
推荐你复制你的appledoc运行目录到你的系统路径（echo $PATH），这样子就能够容易使用。

脚本安装

你也可以使用install-appledoc.sh脚本安装，打开你的终端，进入appledoc的目录，复制下面命令到你的终端

sudo sh install-appledoc.sh (如果你需要模块就加 ‘-t default’)

这样会编译appledoc并且安装到/us/local/bin，并且templates默认在~/.appledoc目录。

Homebrew安装

brew install appledoc

Homebrew默认不会安装注释模块

基本使用

---

使用的时候，只需要下面的命令就行了

appledoc --output ./doc --project-name csdnDoc --project-company "csdn" --company-id "cn.csdn.doc" .

appledoc会扫描当前路径的所有文件，生成文档，打开Xcode ->Documentation and API Reference。里面会看到你的文档。

当需要生成HTML文档时，可以加上”–no-create-docset”
appledoc --no-create-docset --output ./doc --project-name csdnDoc --project-company "csdn" --company-id "cn.csdn.doc" .

然后打到当前目录的.doc文件夹就可以看到文档了。

注释格式

---

类

描述里面支持MarkDown语法，请看下面

/**
 基本类的描述

 换行 ：请空出一行

 ###支持markdown语法，这是三级标题

 ###列表

 - 1 第一列
 - 2 第二列

 初始化方法（tab键 表示代码）

    -(instancetype)initWomenWithAge:(NSInteger) age; //女人初始化的方法
    -(instancetype)initMenWithAge:(NSInteger) age;   //男人初始化的方法

 ###表格例子

 | 表头        | 表头          |
 | -----------|:-------------:|
 | 男          | 不具有         |
 | 女          | 具有           |


 作者：名字 (example@example.com)

 时间：2015-03-29

 */
@interface Person : NSObject

生成的doc文档结构：

方法

详细说明一定要放在@brief的前面，否则@brief注解会把后面的字都用为简要描述来算。

/**
 *  详细说明这个类怎么用
 *
 *  @brief 简要描述该类
 *
 *  @param age 属性描述
 *
 *  @return 返回结果描述
 *  @warning 警告
 *  @bug  臭虫
 *
 *  @since v1.0.0
 *  @deprecated v2.0.0
 *  @see -(instancetype)init;
 */
-(instancetype)initWomenWithAge:(NSInteger) age;

看图不说话：

在我们写平常写代码的时候，经常会用#pragma mark 作为一种标志。其实文档也有这类型的东西。

/**-----------------------------------------------------------------------------
 @name 这个就像那个#pragma mark 作用，就是分割线
 --------------------------------------------------------------------------------
 */

在doc看到是这样子滴：

枚举

枚举比较简单一点，还是看图代码吧

/**
 *  枚举描述
 */
typedef NS_ENUM(NSInteger, AppleDocEnum){
    /**
     *  描述
     */
    AppleDocEnumValue1,
    /**
     *  描述
     */
    AppleDocEnumValue2,
    /**
     *  描述
     */
    AppleDocEnumValue3,
};

惯例，看图：

大家也可以参考下面这几个著名开源的类：
AFHTTPSessionManager.h
TTTAddressFormatter.h
GRMustache.h
MRBrew.h

参考文章：
【Documentation】Written by Mattt Thompson on August 5th, 2013
【 Using AppleDoc to generate Xcode help】Published by Rob
appledoc Github源码地址