在使用apidoc之前，我一直使用wiki来写文档，后来发现这种方式更新起来比较痛苦，时间一长甚至就忘记了更新了。一直在寻找能够使用注释直接生成文档的程序。某一天同事推荐了apidoc，发现这正是我想要的工具。
apidoc原理
apidoc的原理是扫描你的代码文件，提取出注释部分，根据一些规则生成相应的文档。默认的模板久很美观，十分适合作为api文档的生成器。目前apidoc支持的注释基本涵盖了大部分语言的风格了，c，java，php，js，python，perl，lua, Erlang...
安装
需要使用npm安装，如果没有安装npm，请先去https://www.npmjs.com/下载npm并且安装。安装之后使用如下命令安装apidoc
npm install apidoc -g
开始API文档
通常我们的api的是通过一个方法的调用，在mvc架构的c层。如果一个api是 /foo/bar ,那么可以在相关的方法调用中这样写注释
/**
* @api {GET} /foo/bar 一个测试的接口
* @apiName foobar
* @apiVersion 0.1.0
* @apiGroup foo
* @apiDescription 这是一个测试的接口，会输出一个hello world
*/
这样一个最简单的apidoc支持的注释就出现了，接着要做的就是将这些注释生成一袭html文档。在项目的根目录需要建立一个名字为apidoc的json文档
{
"name": "test",
"version": "0.1.0",
"title": "测试项目",
"description": "这是一个测试的项目",
"url": "http://www.imhuchao.com"
}
这些意思都很好了解，name的意思为项目名称，version为版本号，title为项目标题，description为项目的描述，url为接口的地址。比如这里的url是http://www.imhuchao.com，上面写了一个测试接口为/foo/bar，那么生成的文档中的接口地址就会是 http://www.imhuchao.com/foo/bar。
有了apidoc.json，接下来就可以进行文档的生成了，命令为
apidoc -i [input dir] -o [output dir]
需要指定输入和输出的地址，用手敲命令执行比较麻烦，因此我一般是在项目中新建一个脚本，执行脚本就可以自动生成。比如php的可以是
$input = __DIR__;
$output = __DIR__ . '/apidoc';
$shellout = '';
exec("apidoc -f \".*\\.php$\" -i {$input} -o {$output}", $shellout); //这里只需要扫描php文件，其他的文件不生成注释
print_r($shellout);
其他的语言也类似了，或者在linux或者mac上直接使用shell脚本就可以。
关于apidoc命令的使用，可以使用apidoc -h来查看其他的参数，比如自定义模板之类的。
apidoc注释支持的标签
- @api
- @apiDefine
- @apiDeprecated
- @apiDescription
- @apiError
- @apiErrorExample
- @apiExample
- @apiGroup
- @apiHeader
- @apiHeaderExample
- @apiIgnore
- @apiName
- @apiParam
- @apiParamExample
- @apiPermission
- @apiPrivate
- @apiSampleRequest
- @apiSuccess
- @apiSuccessExample
- @apiUse
- @apiVersion
更详细的可以去 http://apidocjs.com/ 查看apidoc的使用。
你可能还喜欢下面这些文章
编译步骤gcc 与 g++ 分别是 gnu 的 c & c++ 编译器。gcc/g++ 在执行编译工作的时候，总共需要4步：预处理,生成 .i 的文件将预处理后的文件转换成汇编语言, 生成文件 .s 有汇编变为目标代码(机器代码)生成 .o 的文件连接目标代码, 生成可执行程序 参数详解-x language filename参数含义为指定文件所使用的语言。根据约定，C语言的后缀名称为".c"，而 C++ 的后缀名为".cpp"或".cc"，但如果你的源代码后缀不约定的那几种，那么需要使用-x参数来指定文件所使用的语言。这个参数对他后面的文件名都起作用。 可以使用的参数吗有下面的这些：
ubuntu中varnish的安装varnish在Ubuntu package 仓库版本可能比较低，,我们一般建议使用varnish-cache.org提供的包。请注意，我们只为Ubuntu的LTS版本（ Long Term Support，长时间支持版本，一般三年）提供安装包,其他中间版本并不提供。但这些版本也许会在较新的ubuntu版本中工作。varnish支持的架构是amd64。使用root执行下面的代码安装varnish提供的最新版本 apt-get install apt-transport-https curl https://repo.varnish-cache.org/GPG-
程序员难免要经常画流程图，状态图，时序图等。以前经常用 visio 画，经常为矩形画多大，摆放在哪等问题费脑筋。有时候修改文字后，为了较好的显示效果不得不再去修改图形。今天介绍的工具是如何使用 Sublime + PlantUML 的插件画流程图，状态图，时序图等。这是一种程序员看了就会爱上的画图方式：自然，高效。什么是 PlantUMLPlantUML 是一个画图脚本语言，用它可以快速地画出：时序图流程图用例图状态图组件图简单地讲，我们使用 visio 画图时需要一个一个图去画，但使用 PlantUML 只需要用文字表达出图的内容，然后就可以直接生成图片。看一个最简单的例子：软件安装这些软件
如果没有额外的设置，iterm2 使用 rzsz 的时候会卡在这个时候就需要使用iterm2提供的trigger来实现rzsz的功能。第一步：本机安装rzsz使用rzsz之前本地也需要安装如果没有安装brew，请先安装brew，mac必备的包管理器！第二步：创建发送和接收脚本发送文件的脚本如下，可以复制下面的内容，保存在 /usr/local/bin/iterm2-send-zmodem.sh中。接收文件的脚本如下，同样可以复制保存在/usr/local/bin/iterm2-recv-zmodem.sh第三步：设置Triggerteigger需要设置两个，一个实发送文件的trigger，一个
这是我的Go学习的第六篇笔记，也是Go入门的最后一篇笔记。在大多数语言中，了解了变量和数据类型，流程控制，函数，面向对象，再加上标准库，就可以用这门语言去写一些项目了。首先让我想想，在工作中通常会用语言频繁处理什么问题或者处理什么数据？最常见的应该是各种字符串操作，日期和时间，读写文件、socket等IO相关的操作！字符串处理 — StringsString提供了一组处理字符串的操作，常用的有：判断一个字符串是否在另一个字符串中分割字符串为[]string和组合[]string为一个字符串字符串替换...太多了，就不一一列举了，这里列出一些常用的字符串操作。字符串判断字符串分割与合并字符串转换
varnishstat是一个查看当前varnish实例的实时运行状态信息。命令以及参数如下：varnishstat 以下选项可用： -1不再显示不断更新的显示，而是将统计信息打印到stdout。-f <glob>Field inclusion glob. Use backslash to escape characters. If the argument starts with '^' it is used as an exclusion glob. Multiple -f arguments may be given, and they will be ap
原标题:每天一个linux命令(1)：ls命令ls 命令是linux下最常用的命令。ls命令就是list的缩写缺省下ls用来打印出当前目录的清单，如果ls指定其他目录那么就会显示指定目录里的文 件及文件夹清单。 通过ls 命令不仅可以查看linux文件夹包含的文件而且可以查看文件权限(包括目录、文件夹、文件权限)，查看目录信息等等。ls 命令在日常的linux操作中用的很多!ls命令格式ls 命令功能列出目标目录中所有的子目录和文件。常用参数-a, –all 列出目录下的所有文件，包括以 . 开头的隐含文件-A 同-a，但不列出“.”(表示当前目录)和“..”(表示当前目录的父目录)。
1、安装libevent官网：http://www.libevent.org/2、安装 BerkeleyDB官网：http://www.oracle.com/technetwork/products/berkeleydb/downloads/index.html（下载需要登录）安装：安装完成之后：或者：添加：并执行：3、安装 MemcacheQ官网：http://memcachedb.org/memcacheq/测试是否安装成功：4、启动服务建立相关目录：启动服务：参数说明：-d : 以后台服务方式运行-l : 设置监听地址及端口（默认是22201）-A : 数据页大小-H : 数据保存目录-
来熟悉熟悉ftp命令，对于服务器之间的文件传输太有用啦，不会怎么能行呢！先来看看基础的命令，包括了连接，列出列表，下载，上传，断开这最基础的命令，会这些，在使用ftp命令行就毫无压力啦！1. 连接ftp服务器格式：ftp a)在linux命令行下输入：b)服务器询问你用户名和密码，分别输入用户名和相应密码，待认证通过即可。2.列出文件列表以及切换目录这部分其实和linux并无区别，分别是ls，和cd列出目录列表切换当前目录3. 下载文件下载文件通常用get和mget这两条命令。a) get格式：get 将文件从远端主机中传送至本地主机中。如要获取远程服务器上/usr/your/1.htm，则
C++中，动态内存管理是通过一对运算符来完成：new 和 delete。new操作符在内存中为对象分配空间并返回一个指向该对象的指针，delete接收一个动态对象的指针，销毁该对象，并释放与之相关的内存。手动管理内存看起来只有这两个操作，似乎很轻松，但实际上这是一件非常繁琐的事情，分配了内存但没有释放内存的场景发生的概率太大了！回想一下，你有多少次打开抽屉却没关上，拿出来的护肤品擦完脸之后却忘了放回去，吃完饭却忘了洗碗。类似这种没有收尾的事情我做的太多了。（以上这些都是在实际生活中我爱人批评我的点）我连这种明面上的事情都能忘记收尾，何况分配内存！所以为了世界和平，我放弃了手动管理内存。好在C+
赞赏
微信赞赏
支付宝赞赏
