/*!\defgroup <模块标签 > {模块名} */
/*!\{*/
模块所囊括的程序源码及注释
/*!\}*/
Doxygen 文档的模块化
Doxygen 提供了 grouping(分组)功能,可实现程序源码中内容相近的文档化内容的归类处理,合理使用该功能可有效提高程序文档结构的逻辑性。Doxygen 的 grouping 可通过三种机制来实现,即模块、成员与子页面,详细介绍可参考 doxygen 手册中的 grouping.html(通常位于 /usr/share/doc/doxygen*/html/grouping.html)。对于制作 C 程序文档而言,只有模块机制是有效的(个人观点)。本文讲述如何按照 Doxygen 的模块文档化规则实现 C 程序文档的模块化。
Doxygen 模块注释格式如下:
模块标签经 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
* \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 会在模块列表中根据模块标签对模块名自动排序。
2008年4月19日 20:24 在C++里用group后生成的文档就不会区分private、protected和public了,郁闷……
2008年4月20日 01:47 我设置的选项主要是针对 c 程序。 doxygen 似乎支持 c++ 是最好的,许多选项默认都是为生成 c++ 文档配置的,多试试各选项的搭配。