文档生成工具-appledoc

发表于 | 分类于 |
字数统计: 1.3k | 阅读时长 ≈ 4

简介

做项目的人多了，就需要文档了。但是就源代码来说，文档最好和源码在一起，这样更新起来更加方便和顺手。象 Java 语言本身就自带 javadoc 命令，可以从源码中抽取文档。今天抽空调研了一下 Objective-C 语言的类似工具。

appledoc是命令行工具，可帮助Objective-C开发人员从特殊格式的源代码注释中生成类似Apple的源代码文档。它旨在为输入提供尽可能可读的源代码注释，并使用注释以及周围的源代码，以HTML的形式生成视觉上吸引人的文档以及完全索引和可浏览的Xcode文档集。虽然有几种工具可以为Objective-C创建HTML文档，但是我所知道的所有工具都无法满足下面描述的最低目标。

appledoc的主要目标：

  • 人类可读的源代码注释。
  • 对对象和成员的简单交叉引用。
  • 生成类似Apple的源代码HTML文档。
  • 生成并安装完全索引和可浏览的Xcode文档集。
  • 单一工具，用于驱动从源代码解析到文档集安装的生成。
  • 轻松定制输出。
  • 100％Objective-C实现，易于调试。

安装

那么简单介绍一下如何安装 appledoc，安装非常简单，只需要 2 步：

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

安装成功:

1
2
3
** INSTALL SUCCEEDED **

install: /tmp/Build/Intermediates.noindex/ArchiveIntermediates/appledoc/InstallationBuildProductsLocation/usr/local/bin/appledoc -> /usr/local/bin//appledoc

另外还有Homebrew：

1
brew install appledoc

Homebrew默认不安装模板。

安装提示

要保持最新，只需转到终端并进入appledoc目录，发出git pull并重新编译appledoc.xcodeproj。不要忘记覆盖已复制到$ PATH的appledoc可执行文件:)

如果您还想编译并运行AppledocTests（单元测试）目标，则需要在构建单元测试目标之前将Libraries＆Frameworks组中指示的所有框架复制到共享框架目录！构建appledoc工具本身不需要这样做。

使用

命令行输入:

1
appledoc --no-create-docset --output ~/Desktop  --project-name Runtime_Demo --project-company iDog --company-id com.iDog /Users/idog/Desktop/Object-C_Demo/Runtime_Demo

成功之后可以看到:

1
appledoc version: 2.2.1 (build 1334)

参数解释:

  • –no-create-docset // 不生成docset类型，生成html
  • –output ~/Desktop // 文档生成的位置
  • –project-name Runtime_Demo //工程的名字，其实这个可以随便取，至少取成工程的名字可以知道这个文档是哪个
  • –project-company // 公司的名称
  • –company-id com.ZQD // 公司的id
  • ~/Desktop/JieLin6/JieLin6/Helpers/ //你要生成文档的注释类所在的文件目录，及工程目录

注释的标准

支持如下三种:

1
2
3
1. /*!  this a test . */
2. /**  this a comment. */
3. /// this is a long comment. */

经常使用的标签：

1
2
3
4
5
6
7
8
@brief : 使用它来写一段你正在文档化的method, PRoperty, class, file, struct, 或enum的短描述信息。
@discusstion: 用它来写一段详尽的描述。如果需要你可以添加换行。
@param:通过它你可以描述一个 method 或 function的参数信息。你可以使用多个这种标签。
@return: 用它来制定一个 method 或 function的返回值。
@see: 用它来指明其他相关的 method 或 function。你可以使用多个这种标签。
@sa:同上
@code ： 使用这个标签，你可以在文档当中嵌入代码段。当在Help Inspector当中查看文档时，代码通过在一个特别的盒子中用一种不同的字体来展示。始终记住在写的代码结尾处使用@endcode标签。
@remark : 在写文档时，用它来强调任何关于代码的特殊之处。

举例：

1
2
/*! @brief This property knows my name. */
@property (nonatomic, strong) NSString *myName;

记录文件常用标签：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
@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名字。

参考文档

项目主页