初试doxygen

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

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

阅读本文前建议先看下以下文档:(注意,网上搜索.安全不保)
1.IBM开发网站上面的资料学习用 doxygen 生成源码文档
2.CU驳壳上面的 Doxygen介绍 (里面的几个注释示例比较好)
3.Linux伊甸园上面的一篇介绍学习用 doxygen 生成源码文档 (这个建议先看)
下面这几个也值得一看:
http://hi.baidu.com/seest/blog/item/efb … afc02.html
http://zhuzhu101011.xhblog.com/archives … 8899.shtml
http://kyle.bloghome.cn/posts/115022.html

OK!
现假定你已经看了上面那三篇文章了.知道了doxygen大概是怎么一回事.
为了让大家更有兴趣..先看个用doxygen生成的文档,链接如下:
demo(注意首页后面那个模块…..)
是不是也有要试一下的冲动呢? 好我们马上开始!

第一步安装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;
}
/** @} */