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

   <p>由于最近琐事比较多，所以好久没有写文章了。今天我们聊一聊Objective-C自动生成文档。</p>    <p>做项目的人多了，就需要文档了。手工写文档是一件苦差事，但是我们也有从源码中抽取注释生成文档的专用工具。</p>    <p>经过查找，比较大众的有三个：</p>    <p>doxygen ：适于生成html文档与pdf文档。 支持的语言多，可以配置的地方也比较多。默认生成的风格与苹果的风格不一致。</p>    <p>headdoc ：是 Xcode 自带的文档生成工具。在安装完 Xcode 后，就可以用命令行来生成对应的文档。不过它只生成以 /*! */ 的格式的注释。不兼容 /** */ 格式的注释</p>    <p>appledoc : Github地址 ，适于生成html文档和xcode帮助文档（docset）。可以兼容 /** */ 格式，也可以兼容 /*! */ 格式的注释。</p>    <p>我感觉appledoc是最好的，所以在这里，我只介绍一下appledoc的使用，有兴趣的童鞋也可以研究下其他两种。</p>    <p>appledoc的安装</p>    <p>第一种：打开终端，输入以下命令：</p>    <pre>  git clone git://github.com/tomaz/appledoc.git  cd appledoc  sudo sh install-appledoc.sh</pre>    <p>第二种：如果你装了homebrew，打开终端，输入以下命令：</p>    <pre>  brew install appledoc</pre>    <p>appledoc的使用</p>    <p>为了演示appledoc的使用，我在桌面新建了一个工程Test，然后在ViewController类里面加了一些注释：</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/6a9f5e52cc397ecd327ec5db7e45dbbb.png"></p>    <p>ViewController.h</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/d2aa53509cdd2d3585977df790c3d54d.png"></p>    <p>ViewController.m</p>    <p>然后演示appledoc的使用：</p>    <p>1.在终端中使用</p>    <p>使用 appledoc 时，打开终端，进入项目所在目录，使用如下命令即可：</p>    <pre>  appledoc --output 输出路径 --project-name 工程名 --project-company 公司名 --company-id 公司ID .</pre>    <p>例如我在这里使用的命令是：</p>    <pre>  appledoc --output ./doc --project-name Test --project-company lisong --company-id lisong .</pre>    <p>具体过程如下：</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/5dfca174ab890b5b3c9ab6358f26f677.gif"></p>    <p>生成Docset</p>    <p>appledoc 会扫描当前路径下的所有文件，然后生成好文档放到 doc 目录下。</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/6e76ff1b9135214ce7f7763b70a50e2c.png"></p>    <p>doc目录</p>    <p>编译出的Docset</p>    <p>默认会放在 ~/Library/Developer/Shared/Documentation/DocSets 路径下，里面包含html的文档。首先显示生成的Docset的包内容，然后在Contents/Resources/Documents路径下，双击打开里面的index.html可以在浏览器中查看文档了。</p>    <p>并且生成的Docset已经安装到Xcode中。重启Xcode后，在 Help—Documentation and API Reference 菜单下也可以看到生成的文档：</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/0157284dbf0e8dd4dc820d2e1b945b81.gif"></p>    <p>在Xcode中查看</p>    <p>如果不想生成Docset，而是想生成html，就需要加一个 --no-create-docset ，这里我使用命令：</p>    <pre>  appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .</pre>    <p>则会在doc目录下生成一个html文件夹，也是双击里面的index.html就可以在浏览器中查看文档了。</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/eae7b8e8f049f5b7125594d052821f2a.png"></p>    <p>html文档</p>    <p>你也可以在终端用 appledoc --help 查看所有可用的参数。</p>    <p>2.在Xcode里使用</p>    <p>1.首先创建一个Aggregate类型的Target，取名Document</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/beac5f8d22687276b52121896bed98fb.gif"></p>    <p>创建Target</p>    <p>2.选择Build Phases，点击左边的小加号，选择New Run Script Phase，建好了以后打开刚刚建立的Run Script，在框里输入命令，命令与终端一样，这里我们输入：</p>    <pre>  appledoc --no-create-docset --output ./doc --project-name Test --project-company lisong --company-id lisong .</pre>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/8c23c6d2cc3da53463f510c4d166dbc2.gif"></p>    <p>添加script</p>    <p>3..然后点左上角选择Document，编译一下，成功后文档就生成在doc目录下了。</p>    <p style="text-align: center;"><img src="https://simg.open-open.com/show/306dba42ec3cdca7cfdd8815543df708.gif"></p>    <p>编译生成文档</p>    <p>注释样式</p>    <p>因为appledoc是通过注释生成文档的，下面说说注释的样式，几种常见的有：</p>    <pre>  /// 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   */</pre>    <p>在Xcode里面，我们可以用 command + option + / 方便快捷地生成注释，很方便。大家可以多尝试尝试各种注释。 </p>    <p>欢迎关注我 和我的专题：iOS技术交流，查看更多好文章。</p>    <p> </p>    <p>来自：http://www.jianshu.com/p/fd4d8d6b6177</p>    <p> </p>