Doxygen 文档的模块化

LiYanrui posted @ Apr 19, 2008 01:36:24 AM in 程序设计 with tags doxygen , 8672 阅读

Doxygen 提供了 grouping(分组)功能,可实现程序源码中内容相近的文档化内容的归类处理,合理使用该功能可有效提高程序文档结构的逻辑性。Doxygen 的 grouping 可通过三种机制来实现,即模块、成员与子页面,详细介绍可参考 doxygen 手册中的 grouping.html(通常位于 /usr/share/doc/doxygen*/html/grouping.html)。对于制作 C 程序文档而言,只有模块机制是有效的(个人观点)。本文讲述如何按照 Doxygen 的模块文档化规则实现 C 程序文档的模块化。

Doxygen 模块注释格式如下:

/*!\defgroup  <模块标签 >  {模块名} */
/*!\{*/

模块所囊括的程序源码及注释

/*!\}*/

模块标签经 Doxygen 处理后,作为 HTML 文件名使用。譬如对于 "M2_List" 这一模块标签,Doxygen 会生成一个名为 "group__M2__Limits.html" 的文件。为了不导致模块的 HTML 文件重名,所以 Doxygen 规定模块标签必须具备唯一性,标签名中不能含有空格。模块名,是显示在程序文档的模块列表中的,这个名字应尽量取得友好一些,以便于理解。譬如对应 "M2_List" 这样的模块标签,模块名可以是 “M2 链表类型”。如果程序文档是 HTML 格式,那么模块标签实际上是 HTML 超级链接地址,而模块名则是超级链接文本。

下面是一份具体的示例:

/*!
 * \file m2.h
 * \brief M2 Project Common Types.
 *
 * M2 Common Types Defination.
 * \author Li Yanrui
 * \date 2008.04.14
 */
#ifndef M2_H
#define M2_H

#include <glib.h>

/*! \defgroup A_M2_Limits M2 程序约定 */
/*!\{*/

#define M2_PI                  G_PI            /*!< pi 预设值,等于 Glib 的 G_PI 宏 */
#define M2_PI_2              G_PI_2          /*!< (pi/2) 预设值 */
#define M2_PI_4              G_PI_4          /*!< (pi/4) 预设值 */
#define M2_DOUB_MAX   G_MAXDOUBLE     /*!< 双精度最大值 */
#define M2_ZERO            G_MINDOUBLE     /*!< 双精度零值 */

/*!\}*/
#endif

如果在 Doxygen 配置文档中设定了 “SORT_GROUP_NAMES = YES”,那么 Doxygen 会在模块列表中根据模块标签对模块名自动排序。

Head_small
四圣兽★白虎 说:
2008年4月19日 20:24 在C++里用group后生成的文档就不会区分private、protected和public了,郁闷……
lyanry 说:
2008年4月20日 01:47 我设置的选项主要是针对 c 程序。 doxygen 似乎支持 c++ 是最好的,许多选项默认都是为生成 c++ 文档配置的,多试试各选项的搭配。

登录 *


loading captcha image...
(输入验证码)
or Ctrl+Enter