Objective-C 自动生成文档工具:appledoc

来源：iOS_小松哥

www.jianshu.com/p/fd4d8d6b6177

如有好文章投稿，请点击 → 这里了解详情

由于最近琐事比较多，所以好久没有写文章了。今天我们聊一聊Objective-C自动生成文档。

做项目的人多了，就需要文档了。手工写文档是一件苦差事，但是我们也有从源码中抽取注释生成文档的专用工具。

经过查找，比较大众的有三个：

doxygen：适于生成html文档与pdf文档。支持的语言多，可以配置的地方也比较多。默认生成的风格与苹果的风格不一致。

headdoc ：是 Xcode 自带的文档生成工具。在安装完 Xcode 后，就可以用命令行来生成对应的文档。不过它只生成以/*! */的格式的注释。不兼容 /** */格式的注释

appledoc: Github地址 https://github.com/tomaz/appledoc，适于生成html文档和xcode帮助文档（docset）。可以兼容 /** */格式，也可以兼容 /*! */格式的注释。

我感觉appledoc是最好的，所以在这里，我只介绍一下appledoc的使用，有兴趣的童鞋也可以研究下其他两种。

appledoc的安装

第一种：打开终端，输入以下命令：

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

cd appledoc

sudo sh install-appledoc.sh

第二种：如果你装了homebrew，打开终端，输入以下命令：

brew install appledoc

appledoc的使用

为了演示appledoc的使用，我在桌面新建了一个工程Test，然后在ViewController类里面加了一些注释：

ViewController.h

ViewController.m

然后演示appledoc的使用：

1.在终端中使用

使用 appledoc 时，打开终端，进入项目所在目录，使用如下命令即可：

appledoc --output 输出路径 --project-name 工程名 --project-company 公司名 --company-id 公司ID .

例如我在这里使用的命令是：

appledoc --output ./doc --project-name Test --project-company lisong --company-id lisong .

具体过程如下：

生成Docset

appledoc 会扫描当前路径下的所有文件，然后生成好文档放到 doc 目录下。

doc目录

编译出的Docset

默认会放在~/Library/Developer/Shared/Documentation/DocSets路径下，里面包含html的文档。首先显示生成的Docset的包内容，然后在Contents/Resources/Documents路径下，双击打开里面的index.html可以在浏览器中查看文档了。

并且生成的Docset已经安装到Xcode中。重启Xcode后，在Help—Documentation and API Reference菜单下也可以看到生成的文档：

在Xcode中查看

如果不想生成Docset，而是想生成html，就需要加一个--no-create-docset，这里我使用命令：

appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .

则会在doc目录下生成一个html文件夹，也是双击里面的index.html就可以在浏览器中查看文档了。

html文档

你也可以在终端用appledoc --help查看所有可用的参数。详细的信息可以查看官方的文档：http://gentlebytes.com/appledoc/

2.在Xcode里使用

1.首先创建一个Aggregate类型的Target，取名Document

创建Target

2.选择Build Phases，点击左边的小加号，选择New Run Script Phase，建好了以后打开刚刚建立的Run Script，在框里输入命令，命令与终端一样，这里我们输入：

appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .

添加script

3..然后点左上角选择Document，编译一下，成功后文档就生成在doc目录下了。

编译生成文档

注释样式

因为appledoc是通过注释生成文档的，下面说说注释的样式，几种常见的有：

/// Single line comment.

/// Single line comment spreading

/// over multiple lines.

/** Single line comment. */

/*! Single line comment */

/**

* Single line comment spreading

* over multiple lines.

*/

/**

Single line comment spreading

over multiple lines. No star

*/

在Xcode里面，我们可以用command + option + /方便快捷地生成注释，很方便。大家可以多尝试尝试各种注释。

更多的注释格式可以看这里：https://github.com/tomaz/appledoc/blob/master/CommentsFormattingStyle.markdown

Objective-C 自动生成文档工具:appledoc相关推荐

Objective-C自动生成文档工具:appledoc
作者 iOS_小松哥关注 2016.12.13 15:47* 字数 919 阅读 727评论 10喜欢 35 由于最近琐事比较多,所以好久没有写文章了.今天我们聊一聊Objective-C自动生成文 ...
项目实战-自动生成文档工具
1.pom 文件 <dependency><groupId>cn.smallbun.screw</groupId><artifactId>screw-c ...
docwizard c++程序文档自动生成工具_如何开发一个基于 TypeScript 的工具库并自动生成文档
为什么用 TypeScript? TypeScript is a typed superset of JavaScript that compiles to plain JavaScript. Any ...
django集成Sphinx，为项目自动生成文档
Sphinx是一个工具,可以轻松创建智能和漂亮的文档,他与Python自带的pydoc是同一类产品,但比pydoc更加优秀,还有很多主题可以选择,平时在开发过程中,我们看到的第三方包的文档,基本上都是 ...
java接口废弃注释_Spring Boot如何让Web API自动生成文档，并解决swagger-annotations的API注解description属性废弃的问题...
前后端分离的系统架构中,前端开发人员需要查看后端WEB API的文档来进行开发.采用后端API文档自动生成的方式,可以大幅提高开发效率.swagger是一个被广泛使用的文档自动生成工具,可以与多种编程 ...
Java使用smart-doc自动生成文档
作为后端开发,写接口文档一直是一个很头痛的问题,今天推荐一个开源工具smart-doc,这个工具基于java原生的注释生成api文档,无需大量的注解配合使用. 官方地址:https://gitee.c ...
【飞书应用】自动生成文档
飞书开放平台飞书开放平台,里面有关于飞书提供的一些供开发者使用的api,可以用来开发飞书的自定义应用,本次使用里面文档相关的api来自动生成文档创建飞书应用可以根据飞书官方文档,创建飞书应用,本 ...
spring boot rest接口自动生成文档（包含swagger）--gradle 下的配置
之前写过一篇文章:spring boot rest接口自动生成文档(包含swagger),这个使用的是maven作为依赖管理工具,现在,让我们体验一下gradle在spring boot项目中如何配置 ...
java前端目录_[Java教程]前端那点事儿——Tocify自动生成文档目录
[Java教程]前端那点事儿--Tocify自动生成文档目录 0 2016-06-29 22:00:07 今天偶然间看到文档服务器有一个动态目录功能,点击目录能跳转到指定的位置:窗口滑动也能自动更新目 ...

Objective-C 自动生成文档工具:appledoc

Objective-C 自动生成文档工具:appledoc相关推荐

最新文章

热门文章