Using Doxygen to generate code documentsContent Table1Install doxygen2Creating a configuration file3Running doxygen4Documenting the code: Comment blocks5Issues6Reference

54 阅读 0 评论 36 点赞

我是靠谱客的博主大意巨人，最近开发中收集的这篇文章主要介绍Using Doxygen to generate code documentsContent Table1Install doxygen2Creating a configuration file3Running doxygen4Documenting the code: Comment blocks5Issues6Reference，觉得挺不错的，现在分享给大家，希望可以做个参考。

概述

Using Doxygen to generate code documents

Content Table

Install doxygen
Creating a configuration file
Running doxygen
Documenting the code: Comment blocks
Issues
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

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.