`
soulmachine
  • 浏览: 112351 次
  • 性别: Icon_minigender_1
  • 来自: 湖北武汉
社区版块
存档分类
最新评论

Doxygen快速入门

 
阅读更多
Java有好用的JavaDoc文档生成工具，那么C++有没有呢？有，这就是大名鼎鼎的Doxygen，开源，功能强大，支持非常多的编程语言。
1.安装和配置
首先下载Doxygen1.5.6，然后下载graphviz-2.18，安装。
运行Doxywizard，开始配置。
单击Wizard按钮，会弹出对话框，输入项目名，这个名字会作为文档的大标题，输入版本，也会出现在文档中，然后输入源代码的根目录，勾选”Scan recursively”，输入文档输出路径。如图1所示：
图1
单击Mode标签，不做任何改动，保持默认。
单击Output标签，选择“prepare for compressed HTML(.chm)”，因为我比较喜欢chm，去掉LaTex。如图2所示：
图2
单击Diagrams标签，如果已经安装了GraphViz，则保持默认，如果没安装，则选择“Use built-in class diagram generator”，如图4所示：
图3
点击OK，返回。
单击Expert按钮，会弹出一个有更多标签页的对话框，在"Project"标签页下，将OUTPUT_LANGUAGE设置为Chinese，因为我需要生成中文文档，如图4所示：
图4
单击"Input"标签，将INPUT_ENCODING保持默认的utf-8，因为我用的是Visual Studio源代码文件的编码默认就是utf-8。如图5所示：
图5
如果你有洁癖，你可以耐心的将FILE_PATTERNS下的后缀一个一个删掉（用记事本打开配置文件，搜索”FILE_PATTERNS”，一下可以删除一片，免去你点鼠标点到食指抽筋之苦），只留下*.h、*.hpp、*.c、和*.cpp等，意思是只扫描C++头文件和源文件，如图6所示：
图6
下拉滚动条，会有EXCLUDE和EXCLUDE_PATTERNS表示不要进行解析的目录和文件，即工程目录下有的目录不需要进行文档化（比如测试代码），就用这两个排除掉。单击“Source Browser”标签，勾选“SOURCE_BROUSER”，这样文档中就会附加一份源码，方便随时查阅，如图7所示：
图7
单击"HTML"标签，勾选“HTML_DYNAMIC_SECTION”，表示要输出chm文件，同时在CHM_FILE输入文件名作为要最终生成的chm文件名，旁边的那个"File.."按钮其实没用。同时点击“HHC_LOCATION”右边的按钮找到chm编译器hhc.exe。如图8所示：
图8
单击OK返回，接下来按“Save...”按钮保存配置文件，文件名随意，如图9所示：
图9
这个配置好的文件以后可以重复利用，每次点”Load…”装载进来，然后点击”Wizard…”，根据不同的工程，修改工程名字，版本，源代码根目录，文档输出目录就可以了，不用再重复上述配置。
接下来在输入Working Directory中一般也输入源代码的根目录，主要是因为配置的一些选项中有的可以用相对路径，这个就可以作为相对路径的参照点。
最后，还要用记事本打开这个配置文件，找到JAVADOC_AUTOBRIEF，将它的值改为YES，即支持JavaDoc的语法，这样就可以用熟悉的JavaDoc风格的文档注释了。
最后单击“Start”按钮开始生成文件，到D:/test下查看，发现多了个html文件夹，进去一看，有很多HTML和一个chm文件，chm文件就是我们所要的文档，不过还不行，chm的左边导航目录是乱码，还需要一些步骤。
首先用一个文本编辑工具（我用VS2008打开，可以显示中文，以gb2312另存的，可是VS2005貌似打开是乱码）打开index.hhc文件，因为这个文件就是目录，然后另存为gb2312编码的文件，覆盖原来的index.hcc。
然后用hhc编译器重新编译，把chm工程文件传给hhc.exe即可，如图10所示：
图10
打开docs.chm，目录是中文的了！
2. 常用注释语法
注释写在对应的函数或变量前面。
简要注释和详细注释：
/**
* @brief Brief Description.
*
* Detailed Description
*/
简要注释和详细注释用一个空行隔开。
JavaDoc风格下，自动会把第一个句号前的文本作为简要注释，后面的为详细注释。你也可以用空行把简要注释和详细注释分开。注意要设置JAVADOC_AUTOBRIEF设为YES。
为了注释一个类中的member，首先要对该类作注释。同样的问题上升到namespace。要注释一个全局的function，typedef，enum或preprocessor定义，你需要首先定义（只能用@file，因为文件不再任何东西里面，就只能用特殊命令实现了，而不像类、函数等，既可以在上方放注释，也可以用@class、@fn进行注释）包含它的文件。
（1）文件头注释
/** @file [file-name]
*@brief brief description.
* @author <list of authors>
* [@author <authors description>]
* @date <date>
* @version <version number>
*
* detailed description for test.cpp
*/
一般@file后我们空着，Doxygen会默认为是@file所在文件的文件名。
[]表示可选，{}表示重复0到N次，<>表示必须参数。@author 表示作者，@data表示日期，@version表示版本号。
（2）类注释
/**
* @class <class-name> [header-file] [<header-name]
* @brief brief description
*
* detailed description
*/
header-file是类声明所在的头文件名字，header-name是要显示的链接文字，一般为头文件的真实路径。
（3）函数注释
/**
* @brief brief description.
* {@param <parameter-name> <parameter description>}
* @exception <exception-object> <exception description>
* {@exception <exception-object> <exception description>}
* @return <description of the return value>
* {@return <description of the return value>}
* @note <text>
* @remarks <remark text>
* {@remarks <remark text>}
* [@deprecated <description>]
* [@since when(time or version)]
* [@see references{,references}]
*/
@可用/代替，但我倾向于用@。
@param 参数名及其解释（我还习惯在param后加[IN]表示输入还是输出参数）
@exception 用来说明异常类及抛出条件
@return 对函数返回值做解释
@note 表示注解，暴露给源码阅读者的文档
@remark 表示评论，暴露给客户程序员的文档
@since 表示从那个版本起开始有了这个函数
@deprecated引起不推荐使用的警告
@see 表示交叉参考
函数的详细注释用@note代替详细注释，因为详细注释要空行隔开，容易忘记。
（4）成员注释
/**<或//<用来注释成员，放在成员后面，格式如下：
int var; /**< Detailed description after the member */
int var; ///< Brief description after the member
此语法对函数成员也适用。
（5）枚举类型注释
/** @brief Another enum, with inline docs */
enum AnotherEnum
{
V1, /**< value 1 */
V2/**< value 2 */
};
一般约定：
（1）每个.h和.cpp文件的头部，必须要有简要注释和详细注释，习惯用法如下：
/** @file
*@brief brief description.
* @author <list of authors>
* @date <date>
* @version <version number>
*
* detailed description for test.cpp
*/
（2）每个类的声明上方，必须要有简要注释和详细注释，习惯用法如下：
/**
* @class
* @brief brief description
*
* detailed description
*/
（3）全局变量和全局宏必须要有注释。
如果注释较短，则可以在上方用
/** @brief some brief description */或右方用
///< some brief description。
进行简要注释。
（4）任何函数都必须要有简要注释和详细注释，习惯用法如下：
/**
* @brief brief description.
* @param <parameter-name> <parameter description>
* @exception <exception-object> <exception description>
* @return <description of the return value>
* @note <text>
* @remarks <remark text>
*/
对于类的函数成员，在头文件的定义处进行简要注释，放在上方：
class Test
{
public:
/** @brief brief description */
int m_test(int a);
}
而在实现出给出详细注释：
/**
* @param [IN] a a integer
* @exception none
* @return 0
* @note detailed description
* @remarks some remarks to be attentioned
*/
int Test::m_test(int a)
{
Return 0;
}
纯虚函数由于没有实现则简要注释和详细注释不需分开。
对于类的数据成员，只在头文件的定义处进行简要注释，不要详细注释。可以在上方用/** @brief some brief description */或右方用///< some brief description。
（5）每个枚举定义必须添加注释,格式如下:
/** Another enum, with inline docs */
enum AnotherEnum
{
V1, //< value 1
V2//< value 2
};
下面是一个简单的例子，完全符合约定：
/** @file
* @brief a brief description for the file.
* @author soulmachine
* @date 2008/07/02
* @version 0.1
*
* detailed description for test.cpp
*/
/** @brief global function, no details
* @note some details about global function
*/
void global_test();
/** @class Test test.h "inc/test.h"
* @brief A test class.
*
* A more elaborate class description.
*/
class Test
{
public:
/** @brief A enum, with inline docs */
enum TEnum {
TVal1, /**< enum value TVal1. */
TVal2, /**< enum value TVal2. */
TVal3/**< enum value TVal3. */
}
//这里Doxygen对enumPtr的处理有点问题
*enumPtr, ///< enum pointer.
enumVar;///< enum variable.
/** @brief A constructor. */
Test();
/** @brief A destructor. */
~Test();
/** @brief a normal member taking two arguments and returning an integer value. */
int testMe(int a,const char *s);
/** @brief A pure virtual member.
* @param [IN] c1 the first argument.
* @param [IN] c2 the second argument.
* @see testMe()
*/
virtual void testMeToo(char c1,char c2) = 0;
int publicVar;//< a public variable.
/** @brief a function variable, note Details. */
int (*handler)(int a,int b);
/** @brief brief before delaration */
int m_func(int a);
};
/** A more elaborate description of the constructor. */
Test::Test()
{
}
/** A more elaborate description of the destructor. */
Test::~Test()
{
}
/**
* @param [IN] a an integer argument.
* @param [IN] s a constant character pointer.
* @return The test results
* @note Details.
* @par
* Another detail.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
*/
int Test::testMe(int a,const char *s)
{
return 0;
}
/**
* @param [IN] a a interger
* @return 0
* @note detailed description
* @remarks remarks,important
* @since 1.0
* @see testMeToo
*/
int Test::m_func(int a)
{
return 0;
}
参考资料：
分享到：
| Google Reader shared items [2008-07-04]
评论
发表评论

您还没有登录,请您登录后再发表评论

相关推荐

    Doxygen快速入门教程

    **Doxygen快速入门教程** Doxygen是一款强大的源代码文档生成工具，广泛应用于C++、C、Java、Python等编程语言。它能够自动生成项目文档，包括类图、时序图、函数接口等，极大地帮助开发者理解和维护代码。本教程将...

    Doxygen 快速入门1

    【Doxygen快速入门1】 Doxygen是一款强大的源代码文档生成工具，支持多种编程语言，包括C++、Java等。在C++领域，它相当于JavaDoc的角色，能够自动生成清晰的API文档。以下是对Doxygen安装配置及注释语法的详细说明...

    代码文档工具Doxygen快速入门V1.00_20120704（ZLG模板）

    ### Doxygen快速入门知识点 #### 一、Doxygen概述 Doxygen是一款强大的开源文档生成工具，支持多种编程语言，如C、C++、Java、Objective-C、IDL等，并且能够生成HTML、PDF、LaTeX等多种格式的文档。Doxygen不仅...

    doxygen使用说明，标准注释说明及快速入门

    快速入门 对于初学者，可以遵循以下步骤快速上手： 1. 安装Doxygen。 2. 使用 `doxygen -g` 创建默认配置文件。 3. 修改配置文件以适应项目需求，如输入文件路径、输出格式等。 4. 在源代码中添加Javadoc风格的...

    Doxygen安装文件及自己整理的教程

    Doxygen进行C++归档快速入门，教程见博客...包含自己整理的Doxygen归档快速入门教程一份，doxygen1.8.4安装文件，doxygen中文手册，graphviz2.30.1绘图安装文件和HtmlHelpWorkShop安装文件HHWorkshop。

    Doxygen入门资料

    ### Doxygen入门指南 #### 一、Doxygen简介 Doxygen是一款非常强大的文档自动生成工具，主要用于从程序源代码中的注释中提取信息，并生成HTML、LaTeX、PDF等多种格式的文档。这对于软件开发团队来说非常重要，因为...

    Doxygen+graphviz+html help workshop

    【描述】中的"doxygen快捷入门"提示，这个压缩包可能包含了一份关于如何快速上手Doxygen的教程，这对于初次使用者来说是非常有价值的资源。Doxygen的使用通常包括配置设置、注释规范和结果生成。配置文件（.doxyfile...

    doxygen中文手册v1.63.pdf

    “开始”章节告诉用户如何快速生成第一个Doxygen文档，是新手入门的绝佳起点；“代码文档化”章节演示了如何将源代码注释文档化，是提高代码可读性和维护性的重要手段；“列表”、“组合”、“包含公式”、“图形和...

    doxygen手册

    #### 三、快速入门 此部分为初次使用者提供了详细的步骤，指导如何使用 doxygen 来生成文档。 - **步骤 0：检查支持的语言**： - 确认 doxygen 是否支持您正在使用的编程语言。 - **步骤 1：创建配置文件**： - ...

    doxygen_manual-1.7.3.pdf

    ### Doxygen 手册知识点概览 #### 一、安装指南与环境配置 - **编译源代码（UNIX系统）...以上是根据《doxygen_manual-1.7.3.pdf》文档内容整理的关键知识点概览，旨在帮助读者快速了解doxygen的主要功能和使用方法。

    Doxygen

    2. **无文档源代码结构提取**：配置Doxygen来从无注释的源文件中提取代码结构，对于快速理解大型源代码库非常有用。同时，还可以通过自动生成的依赖图、继承图和协作图来可视化不同元素之间的关系。 3. **普通文档...

    doc语句快速入门

    本文将深入浅出地介绍`doc`语句的快速入门知识，帮助编程爱好者们提升这方面的能力。 首先，我们要明确一点：`doc`在不同的上下文中可能有不同的含义。例如，在Python中，`__doc__`是一个内置属性，用于存储函数、...

    doxygen_manual-1.8.4

    - **Doxygen** 支持自动链接到类、函数、变量等文档，方便用户快速跳转到相关信息。 通过以上内容的介绍，我们可以了解到 **Doxygen** 不仅仅是一个简单的文档生成工具，它还提供了丰富的功能来帮助开发者更好地...

    ACE win Linux 下的安装和部署以及部分入门级别的资料

    ACE（Adaptive Communication Environment）是一个跨平台的C++框架，专为网络通信和实时系统设计。在Linux操作系统中，...通过以上提供的资料和资源，相信你能够快速入门，并逐步熟练运用ACE进行网络通信应用的开发。

    MakeDoxygen:一个Makefile通用模板，拥有IDE环境的如下特性：子工程列表、文件树、工程选项

    如果你实在想保留金典的散落Makefile风格，MakeDoxygen也可以满足你，这两篇文章会给你启示、2 怎样用到你的工程在决定使用MakeDoxygen前，先验证你的环境是否符合了解MakeDoxygen工作方式快速入门最后看看...

    linux操作系统下c语言编程入门.pdf

    在Linux操作系统下进行C语言编程，涉及到一系列的基础知识点...当然，上述内容只是入门级别的知识点，随着学习的深入，还会有更多的高级特性和概念需要掌握，如内存管理、多线程编程、进程间通信、网络编程和安全性等。

    欧拉公式求圆周率的matlab代码-ramsesGPU:针对大型GPU集群优化的AstrophysicsMHD仿真代码

    使用CMake构建RAMSES-GPU的快速入门（推荐） 可以使用env变量CUDAFLAGS将默认的CUDA编译标志传递给cmake，或在配置命令行上直接设置CMAKE_CUDA_FLAGS（请参见下文）。 git克隆 cd ramsesGPU; mkdir构建 cmake -DUSE_...

    从0到C ——Linux 上 C 语言编程入门

    20世纪70年代和80年代，Unix经历了快速的发展，多个版本相继推出，包括BSD（Berkeley Software Distribution）和System V等。 ###### 2.2.4 现况 今天，Unix仍然被广泛使用，尤其是在企业级应用和高性能计算领域。...

Magicbox
Global site tag (gtag.js) - Google Analytics