初试doxygen

发布于 2009-04-13 21:51:24
rt-thread的API文档是用doxygen从源文件的注释自动生成的...
今天网上搜索一番,整理了个笔记 ...
还不曾用过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;
}

/** @} */

再次运行
doxygen
再看看doc/html/index.html

哈哈.是不是很酷呢?


试想一下.把这个doxygen添加到Makefile里面...
到时候只要 make doc就可以生成最新程序说明文档...那就更酷了....
好了,这里只是简单入门介绍..更多高级功能用到的时候再去研究...

查看更多

关注者
0
被浏览
3.9k
3 个回答
bernard
bernard 2009-04-13
不错,不错。做出来的效果比我的好

撰写答案

请登录后再发布答案,点击登录

发布
问题

分享
好友

手机
浏览

扫码手机浏览