Using Doxygen to generate code documents

Using Doxygen to generate code documents

Content Table

  1. Install doxygen

  2. Creating a configuration file

  3. Running doxygen

  4. Documenting the code: Comment blocks

  5. Issues

  6. Reference



维护用 C/C++ 开发的遗留系统并添加新特性是一项艰难的任务。这涉及几方面的问题：理解现有的类层次结构和全局变量，不同的用户定义类型，以及函数调用图分析等等。

1Install doxygen

doxygen install guide: http://www.doxygen.nl/download.html

If you have the necessary build tools installed (i.e. g++, python, cmake, flex, bison), you should do the following to get the initial copy of the repository:

  • flex is  fast lexical analyzer generator   https://www.gnu.org/software/flex/

git clone https://github.com/doxygen/doxygen.git
cd doxygen

After that you can use

mkdir build
cd build
cmake -G "Unix Makefiles" ..
make

To force a fresh build after an earlier check-out simple remove the build directory and redo the steps above.

After the binaries have been built, you can use

make install

to install them.

2Creating a configuration file

To simplify the creation of a configuration file, doxygen can create a template configuration file for you. To do this call doxygen from the command line with the -g option:

doxygen -g <config-file>

The configuration file has a format that is similar to that of a (simple) Makefile. It consists of a number of assignments (tags) of the form:

TAGNAME = VALUE or 
TAGNAME = VALUE1 VALUE2 ...

一些重要的TAG ：

<OUTPUT_DIRECTORY>：必须在这里提供一个目录名，例如 /home/user1/documentation，这个目录是放置生成的文档文件的位置。如果提供一个不存在的目录名，doxygen 会以这个名称创建具有适当用户权限的目录。
<INPUT>：这个标记创建一个以空格分隔的所有目录的列表，这个列表包含需要生成文档的 C/C++ 源代码文件和头文件。在这里，doxygen 会从这两个目录读取 C/C++ 源代码。如果项目只有一个源代码根目录，其中有多个子目录，那么只需指定根目录并把 <RECURSIVE> 标记设置为 Yes。
<FILE_PATTERNS>：在默认情况下，doxygen 会搜索具有典型 C/C++ 扩展名的文件，比如 .c、.cc、.cpp、.h 和 .hpp。如果 <FILE_PATTERNS> 标记没有相关联的值，doxygen 就会这样做。如果源代码文件采用不同的命名约定，就应该相应地更新这个标记。例如，如果项目使用 .c86 作为 C 文件扩展名，就应该在 <FILE_PATTERNS> 标记中添加这个扩展名。
<RECURSIVE>：如果源代码层次结构是嵌套的，而且需要为所有层次上的 C/C++ 文件生成文档，就把这个标记设置为 Yes。例如，请考虑源代码根目录层次结构 /home/user1/project/kernel，其中有 /home/user1/project/kernel/vmm 和 /home/user1/project/kernel/asm 等子目录。如果这个标记设置为 Yes，doxygen 就会递归地搜索整个层次结构并提取信息。
<EXTRACT_ALL>：这个标记告诉 doxygen，即使各个类或函数没有文档，也要提取信息。必须把这个标记设置为 Yes。
<EXTRACT_PRIVATE>：把这个标记设置为 Yes。否则，文档不包含类的私有数据成员。
<EXTRACT_STATIC>：把这个标记设置为 Yes。否则，文档不包含文件的静态成员（函数和变量）。

用来生成图表的TAG：
在默认情况下，Doxyfile 把 <CLASS_DIAGRAMS> 标记设置为 Yes。这个标记用来生成类层次结构图。要想生成更好的视图，可以从 Graphviz 下载站点 下载 dot 工具。
Graphviz is graph visualization software.
<CLASS_DIAGRAMS>：在 Doxyfile 中这个标记默认设置为 Yes。如果这个标记设置为 No，就不生成继承层次结构图。
<HAVE_DOT>：如果这个标记设置为 Yes，doxygen 就使用 dot 工具生成更强大的图形，比如帮助理解类成员及其数据结构的协作图。注意，如果这个标记设置为 Yes，<CLASS_DIAGRAMS> 标记就无效了。
<CLASS_GRAPH>：如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes，就使用 dot 生成继承层次结构图，而且其外观比只使用 <CLASS_DIAGRAMS> 时更丰富。
<COLLABORATION_GRAPH>：如果 <HAVE_DOT> 标记和这个标记同时设置为 Yes，doxygen 会生成协作图（还有继承图），显示各个类成员（即包含）及其继承层次结构。

3Running doxygen

To generate the documentation you can now enter:

doxygen <config-file>

HTML output

The generated HTML documentation can be viewed by pointing a HTML browser to the index.html file in the html directory.

4Documenting the code: Comment blocks

    Comment blocks for C-like languages (C/C++/C#/Objective-C/PHP/Java)
    Use a block of at least two C++ comment lines, where each line starts with an additional slash or an exclamation mark. Here are examples of the two cases:

///
/// ... text ...
///
or
/**
 * ... text ...
 */

Most often one only wants to put a brief description after a member. This is done as follows:

int var; ///< Brief description after the member

  or

  int var; /**< Detailed description after the member */

For inline documentation this is also possible by starting with the direction attribute, e.g.

void foo(int v /**< [in] docs for input parameter v. */);

example:

 1 /** @ingroup rx_sar_table
 2  *     This data structure stores the RX(receiving) sliding window
 3  *  and handles concurrent access from the @ref rx_engine, @ref rx_app_if
 4  *  and @ref tx_engine
 5  *  @param[in]        rxEng2rxSar_upd_req
 6  *  @param[in]        rxApp2rxSar_upd_req
 7  *  @param[in]        txEng2rxSar_upd_req
 8  *  @param[out]        rxSar2rxEng_upd_rsp
 9  *  @param[out]        rxSar2rxApp_upd_rsp
10  *  @param[out]        rxSar2txEng_upd_rsp
11  */
 

5Issues

How to comment with illustration like following? The illustration pattern goes wrong in generated document generated. May table or markdown should be used.

code comments and generated document

6Reference

1. https://www.ibm.com/developerworks/cn/aix/library/au-learningdoxygen/index.html

2. doxygen official website: http://www.doxygen.nl/index.html


【推广】 免费学中医，健康全家人
原文地址：https://www.cnblogs.com/wordchao/p/11025977.html