初试doxygen

发布于 2009-04-13 21:51:24 浏览：4881 订阅该版

rt-thread的API文档是用doxygen从源文件的注释自动生成的...
今天网上搜索一番,整理了个笔记 ...
还不曾用过doxygen的可以看看
本人发布在本人的小站:[http://www.aozima.com/doc/doxygen/](http://www.aozima.com/doc/doxygen/)
如果你在阅读本人时已是很久以后...可以考虑到上面看看有没有更新

阅读本文前建议先看下以下文档:(注意,网上搜索.安全不保)
1.IBM开发网站上面的资料             [学习用 doxygen 生成源码文档](http://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/)
2.CU驳壳上面的                      [Doxygen介绍](http://blog.chinaunix.net/u2/63610/showart_1722172.html)                 (里面的几个注释示例比较好)
3.Linux伊甸园上面的一篇介绍 学习用  [doxygen 生成源码文档](http://www.linuxeden.com/plus/view.php?aid=61863)         (这个建议先看)
下面这几个也值得一看:
[http://hi.baidu.com/seest/blog/item/efb ... afc02.html](http://hi.baidu.com/seest/blog/item/efb5264cd21a4dfad72afc02.html)
[http://zhuzhu101011.xhblog.com/archives ... 8899.shtml](http://zhuzhu101011.xhblog.com/archives/2008/288899.shtml)
[http://kyle.bloghome.cn/posts/115022.html](http://kyle.bloghome.cn/posts/115022.html)

OK!
现假定你已经看了上面那三篇文章了.知道了doxygen大概是怎么一回事.
为了让大家更有兴趣..先看个用doxygen生成的文档,链接如下:
[demo](http://www.aozima.com/doc/doxygen/html/index.html)(注意首页后面那个模块.....)
是不是也有要试一下的冲动呢? 好我们马上开始!
 
**第一步 安装doxygen**
doxygen的官方网站是:http://www.doxygen.org 其实就是:http://www.stack.nl/~dimitri/doxygen/
各平台下的安装方法我就不啰嗦了.上面那几篇文章里面都有
安装好后运行 doxygen --version 能下学显示版本说明安装好了
 
**第二步 写一个配置文件**
运行 doxygen -g 就可以生成一个默认的配置文件(Doxyfile)
查看这个文件就可以看到每一个参数和详细说明...
不过因为说明过多,不好查看..我们也可以 doxygen -s -g 生成一个没有这么多说明的配置文件

默认的配置文件基本可以满足我的们要求了...
不过有些地方我们要修改下更好一些
```a.) PROJECT_NAME     = "IIC test"    /* 工程名 */
b.) PROJECT_NUMBER   = "Ver 1.0.0"
c.) OUTPUT_DIRECTORY = doc/          /* 这个是文档的输出目录 */
d.) OUTPUT_LANGUAGE  = Chinese       /* 文档的输出语言 这里指文档的模板为中文 并不影响文档内容 */
e.) GENERATE_LATEX   = NO            /* LATEX格式输出我们暂时就先不要了 默认打开了HTML和LATEX输出 */
```

**第三步 从一个实际项目下手**
为了更清楚地搞明白这个是怎么一回事..我们先从空白新建一个项目吧..
为了方便我们先新建一个目录
mkdir test_project
cd test_project
再创建一个doxygen配置文件
doxygen -s -g
再按上面的例子修改它
好了.我们现在运行下:
doxygen
看看发生了什么? OK! 我们看下 doc/html/index.html到底有些什么?
发现什么也没有...这是因为我们什么也没写嘛...文档从何而来...

好! 那么我们现在为这个项目写程序...
假定我们这里面有一个功能要存取IIC设备,于是我们写了一个IIC的驱动
iic.c内容如下:(只是演示.所以以下函数都是空的)
```/* init iic bus */
void iic_init(void)
{
}

/* iic_start */
void iic_start(void)
{
}

/* iic_sendbyte */
bool iic_sendbyte(char send_data)
{
	return 0;
}

/* iic_readbyte */
char iic_readbyte(void)
{
	return 0;
}
```
删除原来生成的文档
再运行下
doxygen
不过doc/html/index.html还是没什么内容...
呵呵,当然嘛.我们并没写什么内容..

下面我们将为我们的代码添加符合doxygen要求的注释
```/**
* @addtogroup IIC
* iic bus device
*/

/** @{ */

/**
* init iic bus 
*/
void iic_init(void)
{
}

/**
* iic_start 
*/
void iic_start(void)
{
}

/**
* iic_sendbyte
* @param  send_data  The date will be send!
* @return if turn ,return 0
*/
bool iic_sendbyte(char send_data)
{
	return 0;
}

/**
* iic_readbyte
* @return  The date of read!
*/
char iic_readbyte(void)
{
	return 0;
}

/** @} */```
再次运行
doxygen
再看看doc/html/index.html

哈哈.是不是很酷呢?