使用AppleDoc生成开发注释文档

作为一种iOS开发者，阅读苹果开发者文档是一个优秀的习惯。Dash工具（无论Mac版还是移动版）的出现，都令这一切变得输入此简单。使用Dash查看文档，每一个类的结构是如此的清晰。那我我们自己的项目如何能够生成和苹果开发者文档一样效果的文档，并能够使用Dash查看呢。还好有第三方工具AppleDoc。笔者无论开发还是写作都推崇一种实用主义。AppleDoc的文档一搜一大把，但是真正能实用的又有哪些？笔者现记录下自己的使用始末，提供给大家参考。

1. 是什么？能干什么

弄清楚目的很重要。一个工具不要觉得不明觉厉就赶紧Down下来用，关键要能满足自己的需求。AppleDoc就是一个文档生成工具，能够根据头文件的注释，公开的属性，方法生成一份类似于苹果开发者文档的文档。生成格式默认为Docset，直接Dash打开查看。

2. 安装

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

安装好后象征性的查看版本

appleDoc --version

输出

appledoc version: 2.2.1 (build 1334)

3. 文档生成

进入项目的工程目录：
appledoc --project-name="projectName" --project-version="3.1.0" --project-company="companyName" --company-id="companyID" --output="./" --docset-install-path="./" .

生成的信息如下：
如果设置设置companyID，则生成文件名为 companyID.projectName.docset
如果不设置则文件名为com.companyname.projectname.projectName.docset
--project-name，--project-company必须输入
--output 为生成的txt文件的目录，这里设置为当前目录
--docset-install-path 为生成docket的目录，这里设置为当前目录。如果此目录不设置，默认会在~/Library/Developer/Shared/Documentation/DocSets/目录生成

就是这样，没有必要再建立一个脚本实现了。

4. 注释

注释使用HeaderDoc风格注释就可以了,
单行注释，只需要//双斜杠注释变成三斜杠注释///就好。
多行注释，加入一些HeaderDoc的标签

• @brief: 简单描述，往往设置为一行。
• @discussion: 详细描述，它不是必须的，仅仅是为了使描述更清晰。
• @param: 描述方法、回调或函数的参数名称。
• @return: 描述方法或函数的返回值。
• @warning 给出警告信息
• @see 参考某个类或者某个方法
• @since 从iOS7开始有效
• ……

注释加入的标签对应于文档中的标签。

下边是一段示例代码

#import <Foundation/Foundation.h>

/**
 这是一个类注释的实例
 这个文档包括了XXXX
 
 这个注释还支持MARKDOWN语法
 ###标题一
 
 标题1的内容
 
 ###标题二
 
 标题1的内容
 
 下边是一段示例代码
 
    NSURL *baseURL = [NSURL URLWithString:@"http://example.com/v1/"];
    [NSURL URLWithString:@"foo" relativeToURL:baseURL];                  // http://example.com/v1/foo
    [NSURL URLWithString:@"foo?bar=baz" relativeToURL:baseURL];          // http://example.com/v1/foo?bar=baz
    [NSURL URLWithString:@"/foo" relativeToURL:baseURL];                 // http://example.com/foo
    [NSURL URLWithString:@"foo/" relativeToURL:baseURL];                 // http://example.com/v1/foo
    [NSURL URLWithString:@"/foo/" relativeToURL:baseURL];                // http://example.com/foo/
    [NSURL URLWithString:@"http://example2.com/" relativeToURL:baseURL]; // http://example2.com/
 
 Also important to note is that a trailing slash will be added to any `baseURL` without one. This would otherwise cause unexpected behavior when constructing URLs using paths without a leading slash.

 这是一个 `NSObject` 的子类
 @warning 这只是一个测试
 */



@interface TestAppleDocComments : NSObject

/**
 *  这是一个枚举类型
 */
typedef NS_ENUM(NSUInteger, EnumType) {
    /**
     *  枚举Type1
     */
    Type1,
    /**
     *  枚举Type2
     */
    Type2,
    /**
     *  枚举Type3
     */
    Type3,
};

/**
 *  枚举类型属性示例
 */
@property (nonatomic, assign) EnumType* myType;

    ///单行属性注释
@property (nonatomic, strong) NSString* testproperty;
/**
 @brief 这是这个属性的简洁描述
 @discussion 这是这个属性的详细描述
 详细信息的描述。如果不写我，那我我和简介描述一样
 
 @warning `testproperty2` must not be `nil`
 */
@property (nonatomic, strong) NSString* testproperty2;
/**
 @brief 这是这个方法的简洁描述，详细信息的描述。如果不写我，那我我和简介描述一样
 @param para1 参数1，这个参数XXXX
 @param para2 参数2 这个参数XXXX
 @return 返回值为id类型
 @warning 这是一个警告
 @see AppDelegate
 @since iOS9.0有效
 */
- (id)testMethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;
/**
 
 默认的全部都是详细描述。
 
 不写brief
 @discussion 这是这个方法的详细描述
 详细信息的描述。如果不写我，那我我和简介描述一样
 @param para1 参数1，这个参数XXXX
 @param para2 参数2 这个参数XXXX
 @return 返回值为id类型
 @warning 这是一个警告
 @see AppDelegate
 @since iOS9.0有效
 */
- (id)test2MethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;

/**
 
 默认的全部都是详细描述。
 不写discussion
 @brief 这是这个方法的简洁描述
 @param para1 参数1，这个参数XXXX
 @param para2 参数2 这个参数XXXX
 @return 返回值为id类型
 @warning 这是一个警告
 @see AppDelegate
 @since iOS9.0有效
*/
- (id)test3MethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;

/**
 这是这个方法的简洁描述
 @discussion 这是这个方法的详细描述
 详细信息的描述。如果不写我，那我我和简介描述一样
 @param para1 参数1，这个参数XXXX
 @param para2 参数2 这个参数XXXX
 @return 返回值为id类型
 @warning 这是一个警告
 @see AppDelegate
 @since iOS9.0以上有效
*/
- (id)test4MethordCommentsWithPara:(NSString*)para1 para:(NSInteger)para2;

@end

生成文档如下图