注释文档

2016-03-07 本文已影响694人与伟大LEE同行

前言

本篇文章主要讲解如何使用不同的工具来生成HTML注释文档 , 对于注释的使用和说明你可以在注释使用这篇文章得到了解.

概述

下面我会为大家讲解如何使用 HeaderDoc 和 Doxygen 还有 Appledoc 工具生成HTML注释文档.

准备

为了方便我们演示不同工具的使用 , 下面我为即将被生成的文档创建一个目录 , 并进行分类 , 每个工具生成的文档会放在各自对应的文件夹中.

文档注释演示目录

使用

HeaderDoc

HeaderDoc 是一个命令行工具 , 允许你从代码中自动生成格式良好的HTML 文档 . 当然 , 注释必须是用指定的格式提供的.

注释的格式在注释使用这篇文章中已经做了较为详细的讲解 , 这里不再叙述 , 如果你需要完整的说明请参见HeaderDoc 用户指南.

其实使用HeaderDoc生成文档的方式有很多种 , 这里我选择为大家讲解使用终端如何操作.

第一步打开终端窗口:

终端窗口

第二步输入命令进入工程根目录 :

cd 你的工程根目录路径

进入工程根目录

第三步使用headerdoc2html命令生成HTML文档:

headerdoc2html的命令格式如下:

headerdoc2html -o OutputDirectory InputDirectory

其中OutputDirectory目录是我们先前创建的目录 , 而InputDirectory目录是工程文件存在的目录.

注意: 在-o后面有一个空格符号。

我这里写好后的命令是这样的(这是我的路径):

headerdoc2html -o /Users/LEE/Desktop/DocDemo/HeaderDoc /Users/LEE/Desktop/QQMusicPlayerDemo/QQMusicPlayerDemo

当你点击回车键后 , 窗口中会巴拉巴拉的显示一堆命令最后当你看到...done后就代表执行完毕了.

生成完毕

打开我们之前创建好的目录 , 里面出现了一大堆文件夹 , 每个文件里对应着我们工程中的每个 .h 和 .m 文件 , 文件夹内是这个文件的注释文档HTML文件.

现在都是零零散散的 , 不方便我们查看 , 最后一步我们要生成一个汇总页面 (类似目录) , 来帮助我们访问整个文档的内容.

命令格式如下:

gatherheaderdoc 文档目录

我这里写好后的命令是这样的(这是我的路径):

gatherheaderdoc /Users/LEE/Desktop/DocDemo/HeaderDoc

完成后你大概会看到这样的信息:

完成后

好了现在我们应该发现文档目录中多了一个名为 masterTOC.html 的文件:

文档目录

(这些文件夹的名称和你工程中.h .m的文件相关)

这个就是我们最后一步生成的汇总页 , 打开后可以看到我在注释使用文章中做演示时所添加注释的文件和方法.

masterTOC.html

我点击进入一个看一看 , 怎么样 ? 是不是非常酷!

文档页面_方法详情

现在 , 你已经看到了结果了 , 随便浏览文档中的任何部分然后看看所有东西都是怎样展现的 . HeaderDoc的用处远远不止这些 , 但是这却是在大多数情况下你需要的东西 , 这里不再一一介绍了 , 更多的细节留给你去慢慢发掘.

Doxygen

Doxygen 是一个第三方应用想要使用它之前必须下载 . 对所有的操作系统它都要对应版本 , 所以当你并不是只为iOS开发时也都可以使用 .

在查看它的细节之前 , 我想说Doxygen并不是一开始就是为了在Objective-C中生成注释文档而设计的 . 但是 , 它却在针对 C 和 C++ 语言时可以完美的完成工作 , 你将会亲眼目睹 , 它其实支持很多的语言 . 除开这些 , 它还包含非常多的注释标签 , 如果你决定了使用 Doxygen 工具来生成注释文档 , 那么你可以使用任何标签来拥有更棒的兼容性.

链接这里你可以找到关于代码注释的所有资源.
链接这里你可以找到Doxygen支持的所有标签，点击每一个标签将会得到它的用途描述信息.
最后，你可以访问链接来下载应用.

在下载前 , 让我提醒你可以在 Doxygen 的网站上找到比我先前在注释使用文章中提到的内容多得多的东西 . 实际上 , 正如下面的截图所示 , 在左侧有一个菜单面板 , 你可以使用它来找到的 Doxygen 各个部分的内容和数不尽的细节以及how-tos.

现在 , 访问我刚才在上面给你的链接地址 , 然后滑到页面的下方直到找到一个名叫A binary distribution for Mac OS X 10.5 and later 的区域 . 点击 ftp或http链接来初始化包下载过程 . 依据你的网络速度 , 下载过程可能会需要几秒钟来完成 , 文件大小大概为55Mb.

下载完成后 , 打开包 . 然后找到Doxygen应用然后把它拖到你的Applications目录下.

如果你不想把它添加到Applications目录下也没问题 , 可以把它拖到任何你想放的位置 . Doxygen 是一个完全self-contained的应用 , 无论你把它放在哪里 , 移除它只需要删除它的APP文件.

假设现在你已经把它复制到了目录下 , 点击Lauchpad来轻松找到它 . 点击它运行.

注意: 如果得到一个提示信息说一个应用程序不能被打开是因为它来自没有被认证的开发者，按照下面的步骤来跳过它 : 在Finder里 , 打开Applications目录 . 定位到Doxygen应用 , 然后按下Ctrl键+点击它 . 在菜单中选择 Open 选项 , 然后在新的视图框中点击Open 按钮.

如果以前用过Doxygen，你肯定知道应该怎么做。但是，这里我假设你是第一次使用这个应用，所以让我向你展示一些最重要的步骤.

下面是Doxygen第一次运行时的初始窗口：

初始窗口

在我告诉你正确的需要使用的设置信息前 , 有必要说明Doxygen提供两个使用模式 : Wizard模式由一个简单且通用的方法组成 , 以及Expert模式 , 在这里很多的配置信息都可以被指定这样你可以定制化每一个输出文档的细节部分.

我不会把重点放在Expert模式上 , 因为要应用的配置条件高度依赖于每位开发者的个人需求 . 意味着我们将专注于 Wizard 模式 , 但是在此之前 , 我想还是有必要快速了解一下Expert模式 . 在主视图区域里点击 Expert按钮 , 马上就会在主面板上看到给了你很多的配置信息 . 你可以上下滑动查看所有的配置 , 但是远不止于此 . 在左边 , 有一个小面板标题为Topics , 点击其他的topic就可以获取它自己的配置 . 如果有时间 , 浏览它们所有 . 你将会找到想在你的应用当中使用的有用的选项.

现在 , 我们把焦点放在Wizard模式 . 确保点击到了正确的按钮 , 这样就可以跟上我将要描述的内容 . 首先 , 在视图顶部我们必须指定 Doxygen 从哪里运行 . 点击Select按钮 , 然后在电脑里选择Application目录 , 或者任何其他你把Doxygen应用拷贝进去的那个目录.

接下来 , 我们来指定工程名字 . 在Project Name输入框里 , 输入 DocDemo in Objective-C值 (或者任何你想用的值) . 如果你愿意 , 也可以把下面的输入框值都填上 . 在那之下 , 我们必须指定指向工程的路径 . 再一次 , 使用Select按钮且定位到工程的根目录中 . 选中 Scan recursively 会很不错 , 因为Doxygen就也可以扫描所有子目录了.

最后 , 指定存储生成的文档的地方 . 如果你还记得的话 , 我们已经为此在桌面的 DocDemo 目录下新建了子目录Doxygen . 因此 , 点击 Destination Directory 旁边的 Select 按钮 , 然后选中它.

接下来 , 在左边的 Topics 列表里 , 选择Mode选项 . 在新的配置里 , 选中All Entities 选项:

接下来 , 还是在 Topics 列表里 , 选择 Output 选项 . 在这里你可以找到很多的导出选项 . 自由选择任何你想要的output种类 . 在这个例子里 , 我屏蔽了 LaTeX选项 , 只让HTML有效.

最后 , 在Diagrams选项里你可以保留默认设置.

现在是时候输出文档了 . 请确认在继续之前一定要把先前的配置信息全部设置好 . 设置好了 ? 很好，我们继续吧 . 点击Run按钮 (在Wizard和Expert 按钮旁边) ，然后现在在主视图区域你可以看到一个名叫Run doxygen的新按钮 . 点击它让应用帮你启动创建HTML文件 . 在白色区域你将会看到一些output信息 , 如果事情出差错了 , 你也会在这里看到.

不管怎样 , 只要它完成了 , 打开Finder然后定位到输出目录去查看导出文件 . 你会看到有一系列的文件被创建了 , 而你需要找到的就是 index.html 文件 . 双击在浏览器中打开它 . 其实如果你不是那么在意非要看到导出的文件 , 可以简单在Doxygen视图里点击Show HTML output.

这是在打开index页面时看到的第一个屏幕:

它只是包含了我们先前设置的工程名 , 创建时间 , 和在顶部的许多链接 . 使用这些链接去浏览一下相应内容 . 例如 , 如果点击Classes链接 , 你就会得到一个包含了工程中的所有classes的列表 . 有趣的部分是在每个class旁边都展示了它的简短描述信息 (仅仅是那些我们写了的).

下面是当你点击 LaunchViewController class时会看到的内容：

可以看到 , 工程中的方法和一个公有属性的详细文档可以在这里找到 . 另外一个有趣的地方是在Files菜单下面 , 在这里所有的被分析的文件都被列举出来，选中LaunchViewController.h文件 . 在哪里你可以找到文件的描述信息 , 以及我们声明的所有东西: calss , protocol , 和struct.

使用More…链接来查看上面的所有内容的详细信息 . 还有一个链接名字为 "Go to the source code of this file." 如果点击它 , 将会展现LaunchViewController.h头文件里的代码 . 注意不管在头文件里的任何public的内容 , 都可以在这里展示出来 . 但是不要指望可以看到任何实现代码 , 那些是“专属于你”的 .

好了 , 此刻我相信你已经对所有以上内容有了大概理解 . 定位到输出的HTML页面 , 回到Xcode中修改注释文档信息 , 然后重新导出所有内容 . 还有 , 不要犹豫去设置高级配置信息然后查看将会发生什么 . 大体上 , 尽量多的体验更多内容 , 然后更加熟悉Doxygen . 无论是小工程还是大工程 , 它都是一个很棒的工具.

Appledoc

appledoc 是一个可以帮你生成Objective-C代码注释的辅助工具 , appledoc所生成的注释API文档与苹果类库的API文档保持一致 . 这可以让Xcode能够识别出我们自己的API文档.

废话不多说 , 直接进入正题 , 首先我们要下载安装appledoc , 它在GitHub上 , 接下来我们通过终端来下载安装它.

下载 (大概40多MB)

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

下载完成

进入appledoc目录

cd ./appledoc

安装 (可能会需要你输入密码)

sudo sh install-appledoc.sh

安装完成

稍等片刻就安装完成了 , 接下来我们验证一下是否安装成功 , 命令如下:

appledoc --version

查看版本

我当前的版本是2.2.1 (以你实际的为准) .

下载安装好后 , 我们来讲一下如何使用appledoc.

第一步 , 在终端中进入工程根目录:

cd 你的工程根目录路径

第二步 , 执行appledoc的命令格式如下:

appledoc --project-name QQMusicPlayerDemo --project-company LEE ./

QQMusicPlayerDemo:项目名称
lee：公司名称
根据你的实际情况去替换

还可以设置详细一些:

appledoc --project-name QQMusicPlayerDemo --project-company LEE  --company-id com.lee --output /Users/LEE/Desktop/QQMusicPlayerDemo /Users/LEE/Desktop/QQMusicPlayerDemo/QQMusicPlayerDemo

以上命令中分别需要提供5个参数,分别是:

1:工程名称
2:公司名称
3:工程ID
4:生成结果输出路径
5:扫描哪个路径下的类.

注意: 以上命令不要有换行 , 其中扫描路径最好使用工程根目录下的工程名那个路径 , 不要直接使用工程根目录如果集成了 CocoaPods 那么生成时基本上都会报错
提示过了再错
"( *・ω・)✄╰ひ╯ 那么我们又可以聊聊人生了

执行之后你会看到工程的根目录下会多出一个文件 , 该命令会根据指定的路径将所有的的类遍历一次 , 当生成成功以后 , appledoc会新建一个文本文件来记录生成情况 , 这个文件存放在上面命令中指定的--output路径下(我命令里写的是工程根目录):

如果你还想了解更多appledoc的命令可以执行:

appledoc --help

生成的文档会自动存放在Xcode默认的文档目录里:
~/Library/Developer/Shared/Documentation/DocSets

第三步 , 集成到工程中

其实只要在终端执行上面的一句命令就可以完成文档的生成 , 如果你想每次编译工程时自动去生成相应的文档那么这一步就可以帮到你.

在你的工程中创建新的 Target , 注意这里要选择 Other 中的 Aggregate , 如图所示:

Aggregate

在我们新创建的 Target 中的 Buid Phases 中添加 Run Script:

添加运行脚本

打开Run Script , Shell 下面的文档区域添加这样的模板:

#appledoc Xcode script 
# Start constants 
company="LEE";
companyID="com.lee";
companyURL="http://lee.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}.lee" \
--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}"/"${PROJECT_NAME}"

Xcode 左上角选择这个 Target , 然后 Build 编译.

选择Target

这是我们的文档文件就生成好了 , 打开之前在根目录生成的 docset-installed.txt 文件

docset-installed.txt

选中其中的路径然后前往该路径.

文档目录

这个就是我们生成的文档

这里介绍2种查看方式 :

使用Xcode文档接口查看工具

* 顶部工具栏中选择 __Window -> Documentation and API Reference__ 或者使用快捷键 __Shift + command + 0__

Documentation and API Reference

* 左侧找到我们的文档 点击它就可以查看了.

文档首页

文档详情页面

使用浏览器查看HTML页面

* 找到文档文件 -> 右键 显示包内容

显示包内容

* 按照这个路径找到index.html (Documents文件夹就是整个HTML文档的目录)

index.html

浏览器-文档首页

怎么样 ? 是不是瞬间感觉人生完整了. 有了appledoc 我们可以轻松生成出和苹果官方一样的文档来.

语法

注释块中，每一行开头的空格和"*"字符多数情况都会被appledoc忽略。
连续的两行(即没有间隔空行)的注释，将被合并成一个段落，并忽略换行，就像html。

注释类型

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

在注释块内，appledoc支持如下语法：Markdown、HTML、HeaderDoc Tags.

Markdown的语法在这里有介绍(中文翻译) , 用Github和简书的童鞋应该很熟悉 . OSX上可以用Mou实时查看效果 , Chrome也有一个插件来实时查看效果 . 这个东西可以说一看就会 , 学习成本很低 . Markdown有很多方言 , 而且appledoc支持的也不算完整 . 所以用的时候可以试着在appledoc编译一下看看效果 .

HTML这个就不用说了 , 支持Markdown肯定也支持HTML .. 如果想要把控住更多细节 , 那就直接码HTML吧.

HeaderDoc Tags这个东西是苹果的HeaderDoc工具的语法。详情可以见官网文档。例如@param、@return、@warning这样的东西，appledoc会进行解释。当然appledoc对这个东西的支持也不算完整 :?: 所以用的时候也要尝试一下。

用法示例

/** 第一行是类的简介

 在简介的下面,就是类的详细介绍了。
 没有间隔换行会被消除，就像HTML那样。

 下面是常用的markdown语法

 - - -

 无序列表: (每行以 '*'、'-'、'+' 开头):

 * this is the first line
 * this is the second line
 * this is the third line

 有序列表: (每行以 1.2.3、a.b.c 开头):

 a. this is the first line
 b. this is the secode line

 多级列表:

 * this is the first line
 a. this is line a
 b. this is line b
 * this is the second line
 1. this in line 1
 2. this is line 2

 标题:

 # This is an H1
 ## This is an H2
 ### This is an H3
 #### This is an h4
 ##### This is an h5
 ###### This is an H6

 链接:

 普通URL直接写上，appledoc会自动翻译成链接: http://www.jianshu.com/users/a6da0db100c8

 [这个](http://www.jianshu.com/users/a6da0db100c8) 链接会隐藏实际URL.

 表格:

 | header1 | header2 | header3 |
 |---------|:-------:|--------:|
 | normal  |  center |  right  |
 | cell    | cell    | cell    |


 引用:

 这里会引用到方法 `someMethod:`，这里会引用到类 `CustomColor`

 这里会引用到一个代码块

        void CMYK2RGB(float c, float m, float y, float k,
        float *r, float *g, float *b) {
            *r = (1 - c) * (1 - k);
            *g = (1 - m) * (1 - k);
            *b = (1 - y) * (1 - k);
        }

 @since iOS5.0

 */

@interface AppledocExample : NSObject

///这里是属性的说明
@property (nonatomic, strong) NSString *name;

/** 
@brief 这里是方法的简介。该Tag不能放到类注释里。
@exception UIColorException 这里是方法抛出异常的说明
@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

编译出的效果是这样:

总结

上面所介绍的这三种工具都是非常不错的 , 你可以根据自己的喜欢去选择 , 不过我个人还是比较推荐Appledoc的 , 它默认生成的文档风格和苹果的官方文档是一致的 , 而doxygen需要另外配置 . appledoc就是用objective-c生成的 , 必要的时候调试和改动也比较方便 . 可以生成docset , 并且集成到xcode中 . 这一点是很赞的 , 相当于在源码中按住option再单击就可以调出相应方法的帮助 . 相对于headerdoc , 它没有特殊的注释要求 , 可以用/** / 的格式 , 也可以兼容/! */的格式的注释 . 综合来看所以我比较推荐Appledoc .

我是LEE , 如果你还有更好的建议欢迎给我留言 , 如果喜欢记得点赞哟 ! 么了个哒~

注: 本文中Doxygen部分参考自AppCoda.

注释文档

前言

概述

准备

使用

HeaderDoc

Doxygen

Appledoc

语法

总结

猜你喜欢

热点阅读