认真整理的一份Doxygen用法，希望对你有所帮助

最新推荐文章于 2024-08-02 16:28:35 发布

木喳喳

最新推荐文章于 2024-08-02 16:28:35 发布

阅读量3.7k

点赞数 6

文章标签：代码注释 API文档 Linux

本文链接：https://blog.csdn.net/qq_25645313/article/details/93711643

版权

Doxygen简介

Doxygen是用于从带注释的C ++源生成文档的事实上的标准工具，但它也支持其他流行的编程语言，如C，Objective-C，C＃，PHP，Java，Python，IDL（Corba，Microsoft和UNO / OpenOffice风格）），Fortran，VHDL，Tcl，并在某种程度上.

Doxygen可以通过三种方式帮助您：

它可以LATEX从一组记录的源文件生成在线文档浏览器（以HTML格式）和/或离线参考手册（in ）。还支持在RTF（MS-Word），PostScript，超链接PDF，压缩HTML和Unix手册页中生成输出。文档直接从源代码中提取，这使得文档更容易与源代码保持一致。
您可以配置 doxygen以从未记录的源文件中提取代码结构。这对于在大型源代码分发中快速找到方法非常有用。Doxygen还可以通过包括依赖图，继承图和协作图来可视化各种元素之间的关系，这些都是自动生成的。
您也可以使用doxygen创建正常文档（就像我为doxygen用户手册和网站所做的那样）。

Doxygen是在Mac OS X和Linux下开发的，但设置为高度便携。因此，它也可以在大多数其他Unix版本上运行。此外，还提供Windows的可执行文件。

Doxygen安装

#在Ubuntu下使用apt-get install命令即可安装doxygen命令行工具，命令如下：
sudo apt-get install doxygen

#在CentOS下使用yum install命令即可安装doxygen命令行工具，命令如下：
sudo yum install doxygen

Graphviz安装

#在Ubuntu下使用apt-get install命令即可安装Graphviz工具，命令如下：
sudo apt-get install graphviz

#在CentOS下使用yum install命令即可安装Graphviz工具，命令如下：
sudo yum install graphviz

第1步：创建配置文件

Doxygen使用配置文件来确定其所有设置。每个项目都应该有自己的配置文件。项目可以包含单个源文件，但也可以是递归扫描的整个源树。

为了简化配置文件的创建，doxygen可以为您创建模板配置文件。要执行此操作，请doxygen从命令行调用以下-g选项：

doxygen -g <config-file>

其中<config-file>是配置文件的名称。如果省略文件名，将创建一个名为Doxyfile的文件。如果名称为<config-file>的文件已存在，则doxygen会在生成配置模板之前将其重命名为<config-file> .bak。如果您使用-（即减号）作为文件名，那么doxygen将尝试从标准输入（stdin）读取配置文件，这对脚本编写非常有用。

该文件基本上由赋值语句列表组成。每个语句都包含一个TAG_NAME大写字母，后跟等号（=）和一个或多个值。如果一个标记被分配一次多次，则最后一个分配将覆盖任何先前的分配。如果一个标记的值是一个参数列表，则使用（+=）操作而不是（=）。

TAGNAME = VALUE or
TAGNAME = VALUE1 VALUE2 ...

第2步：常用选项

## This tag specifies the encoding used for all characters in the config file
# that follow. The default is UTF-8 which is also the encoding used for all text
# before the first occurrence of this tag. Doxygen uses libiconv (or the iconv
# built into libc) for the transcoding. See http://www.gnu.org/software/libiconv
# for the list of possible encodings.
# The default value is: UTF-8.
DOXYFILE_ENCODING      = UTF-8    #doxygen文件的编码格式

# The PROJECT_NAME tag is a single word (or a sequence of words surrounded by
# double-quotes, unless you are using Doxywizard) that should identify the
# project for which the documentation is generated. This name is used in the
# title of most generated pages and in a few other places.
# The default value is: My Project.
   
PROJECT_NAME           = "doxygen test"  #文档工程名

# The PROJECT_NUMBER tag can be used to enter a project or revision number. This
# could be handy for archiving the generated documentation or if some version
# control system is used.
    
PROJECT_NUMBER         =  "v1.0.0" #文档版本号

# Using the PROJECT_BRIEF tag one can provide an optional one line description
# for a project that appears at the top of each page and should give viewer a
# quick idea about the purpose of the project. Keep the description short.
        
PROJECT_BRIEF          = "doxygen brief" #一行描述，说明文档的目的

# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.
                         
OUTPUT_DIRECTORY       =   #指定生成文档的存储路径，缺省值使当前路径

# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# Possible values are: Afrikaans, Arabic, Armenian, Brazilian, Catalan, Chinese,
# Chinese-Traditional, Croatian, Czech, Danish, Dutch, English (United States),
# Esperanto, Farsi (Persian), Finnish, French, German, Greek, Hungarian,
# Indonesian, Italian, Japanese, Japanese-en (Japanese with English messages),
# Korean, Korean-en (Korean with English messages), Latvian, Lithuanian,
# Macedonian, Norwegian, Persian (Farsi), Polish, Portuguese, Romanian, Russian,
# Serbian, Serbian-Cyrillic, Slovak, Slovene, Spanish, Swedish, Turkish,
# Ukrainian and Vietnamese.      
# The default value is: English. 
                                
OUTPUT_LANGUAGE        = English  #输出文档的语言，缺省值是english,支持生成简体中文

# The INPUT tag is used to specify the files and/or directories that contain
# documented source files. You may enter file names like myfile.cpp or
# directories like /usr/src/myproject. Separate the files or directories with
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
                             
INPUT                  =        #指定包含文件的源文件的文件 和/或 目录，缺省值是当前目录

# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
# libiconv (or the iconv built into libc) for the transcoding. See the libiconv
# documentation (see: http://www.gnu.org/software/libiconv) for the list of
# possible encodings.         
# The default value is: UTF-8.
                                                                                                                                                                             
 INPUT_ENCODING         = UTF-8   #指定源文件的字符编码

# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard patterns (like *.cpp and
# *.h) to filter out the source-files in the directories.
#                               
# Note that for custom extensions or not directly supported extensions you also
# need to set EXTENSION_MAPPING for the extension otherwise the files are not
# read by doxygen.              
#                               
# If left blank the following patterns are tested:*.c, *.cc, *.cxx, *.cpp,
# *.c++, *.java, *.ii, *.ixx, *.ipp, *.i++, *.inl, *.idl, *.ddl, *.odl, *.h,
# *.hh, *.hxx, *.hpp, *.h++, *.cs, *.d, *.php, *.php4, *.php5, *.phtml, *.inc,
# *.m, *.markdown, *.md, *.mm, *.dox, *.py, *.pyw, *.f90, *.f95, *.f03, *.f08,
# *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf and *.qsf.
                                 
FILE_PATTERNS          = *.h \ #对头文件和源文件的文档化信息生成程序文档
                         *.c

# The RECURSIVE tag can be used to specify whether or not subdirectories should
# be searched for input files as well.
# The default value is: NO. 
                           
RECURSIVE              = YES    #递归遍历当前目录的子目录，寻找被文档化的程序文件

# The EXCLUDE tag can be used to specify files and/or directories that should be
# excluded from the INPUT source files. This way you can easily exclude a
# subdirectory from a directory tree whose root is specified with the INPUT tag.
#                       
#Note that relative paths are relative to the directory from which doxygen is
# run.                  
                                                                                                                                                                              
EXCLUDE                =    #指定应从输入源文件中排除的文件和/或目录

# If the value of the INPUT tag contains directories, you can use the
# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
# certain files from those directories.
#                        
# Note that the wildcards are matched against the file with absolute path, so to
# exclude all test directories for example use the pattern */test/*
                         
EXCLUDE_PATTERNS       =  #指定需要从INPUT标记包含的通配符需要特别排除的某些文件

# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources                                                                                             
# only. Doxygen will then generate output that is more tailored for C. For
# instance, some of the names that are used will be different. The list of all
# members will be omitted, etc.
# The default value is: NO.
           
OPTIMIZE_OUTPUT_FOR_C  = YES #如果是制作的C程序文档，该选项必须设置成YES，否则默认为C++

# When TYPEDEF_HIDES_STRUCT tag is enabled, a typedef of a struct, union, or
# enum is documented as struct, union, or enum with the name of the typedef. So
# typedef struct TypeS {} TypeT, will appear in the documentation as a struct
# with name TypeT. When disabled the typedef will appear as a member of a file,
# namespace, or class. And the struct will be named TypeS. This can typically be
# useful for C code in case the coding convention dictates that all compound
# types are typedef'ed and only the typedef is referenced, never the tag name.
# The default value is: NO.  
#对于使用 typedef 定义的结构体、枚举、联合等数据类型，只按照 typedef 定义的类型名进行文档化
TYPEDEF_HIDES_STRUCT   = YES

# If the HIDE_SCOPE_NAMES tag is set to NO then doxygen will show members with
# their full class and namespace scopes in the documentation. If set to YES, the
# scope will be hidden.
# The default value is: NO.
# 在 C++ 程序文档中，该值可以设置为 NO，而在 C 程序文档中，由于 C 语言没有所谓的域/名字
# 空间这样的概念，所以此处设置为 YES
HIDE_SCOPE_NAMES       = YES

# The QUIET tag can be used to turn on/off the messages that are generated to
# standard output by doxygen. If QUIET is set to YES this implies that the
# messages are off.
# The default value is: NO.
# 让 doxygen 静悄悄地为你生成文档，只有出现警告或错误时，才在终端输出提示信息
QUIET                  = YES

# If the REFERENCED_BY_RELATION tag is set to YES then for each documented
# function all documented functions referencing it will be listed.
# The default value is: NO.
# 允许程序文档中显示本文档化的函数相互调用关系
REFERENCED_BY_RELATION = YES

# If the REFERENCES_RELATION tag is set to YES then for each documented function
# all documented entities called/used by that function will be listed.
# The default value is: NO.

REFERENCES_RELATION    = YES

# If the REFERENCES_LINK_SOURCE tag is set to YES and SOURCE_BROWSER tag is set
# to YES then the hyperlinks from functions in REFERENCES_RELATION and
# REFERENCED_BY_RELATION lists will link to the source code. Otherwise they will
# link to the documentation.
# The default value is: YES.

REFERENCES_LINK_SOURCE = YES

# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES.

GENERATE_LATEX         = YES # 生成 latex 格式的程序文档

# 在程序文档中允许以图例形式显示函数调用关系，前提是你已经安装了 graphviz 软件包

# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
# available from the path. This tool is part of Graphviz (see:
# http://www.graphviz.org/), a graph visualization toolkit from AT&T and Lucent
# Bell Labs. The other options in this section have no effect if this option is
# set to NO
# The default value is: YES.

HAVE_DOT               = YES

# If the CALL_GRAPH tag is set to YES then doxygen will generate a call
# dependency graph for every global function or class method.
#
# Note that enabling this option will significantly increase the time of a run.
# So in most cases it will be better to enable call graphs for selected
# functions only using the \callgraph command. Disabling a call graph can be
# accomplished by means of the command \hidecallgraph.
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.

CALL_GRAPH             = YES

# If the CALLER_GRAPH tag is set to YES then doxygen will generate a caller
# dependency graph for every global function or class method.
#
# Note that enabling this option will significantly increase the time of a run.
# So in most cases it will be better to enable caller graphs for selected
# functions only using the \callergraph command. Disabling a caller graph can be
# accomplished by means of the command \hidecallergraph.
# The default value is: NO.
# This tag requires that the tag HAVE_DOT is set to YES.

CALLER_GRAPH           = YES

# If the SOURCE_BROWSER tag is set to YES then a list of source files will be
# generated. Documented entities will be cross-referenced with these sources.
# Note: To get rid of all source code in the generated output, make sure that
# also VERBATIM_HEADERS is set to NO.
# The default value is: NO.

SOURCE_BROWSER         = NO # 把所有的源代码包含在其中

# The GENERATE_TREEVIEW tag is used to specify whether a tree-like index
# structure should be generated to display hierarchical information. If the tag
# value is set to YES, a side panel will be generated containing a tree-like
# index structure (just like the one that is generated for HTML Help). For this
# to work a browser that supports JavaScript, DHTML, CSS and frames is required
# (i.e. any modern browser). Windows users are probably better off using the
# HTML help feature. Via custom style sheets (see HTML_EXTRA_STYLESHEET) one can
# further fine-tune the look of the index. As an example, the default style
# sheet generated by doxygen has an example that shows how to put an image at
# the root of the tree instead of the PROJECT_NAME. Since the tree basically has
# the same information as the tab index, you could consider setting
# DISABLE_INDEX to YES when enabling this option.
# The default value is: NO.
# This tag requires that the tag GENERATE_HTML is set to YES.
#这会在HTML文档中，添加一个侧边栏，并以树状结构显示包、类、接口等的关系
GENERATE_TREEVIEW      = YES

# If the PDF_HYPERLINKS tag is set to YES, the LaTeX that is generated is
# prepared for conversion to PDF (using ps2pdf or pdflatex). The PDF file will
# contain links (just like the HTML output) instead of page references. This
# makes the output suitable for online browsing using a PDF viewer.
# The default value is: YES.
# This tag requires that the tag GENERATE_LATEX is set to YES.

PDF_HYPERLINKS         = YES #生成PDF文档

# If the USE_PDFLATEX tag is set to YES, doxygen will use pdflatex to generate
# the PDF file directly from the LaTeX files. Set this option to YES, to get a
# higher quality PDF documentation.
# The default value is: YES.
# This tag requires that the tag GENERATE_LATEX is set to YES.

USE_PDFLATEX           = YES #使用LaTeX来生成PDF文档

# If the EXTRACT_ALL tag is set to YES, doxygen will assume all entities in
# documentation are documented, even if no documentation was available. Private
# class members and static file members will be hidden unless the
# EXTRACT_PRIVATE respectively EXTRACT_STATIC tags are set to YES.
# Note: This will also disable the warnings about undocumented members that are
# normally produced when WARNINGS is set to YES.
# The default value is: NO.

EXTRACT_ALL            = YES

第3步：文档生成

#在Doxygen所在路径下运行
$ doxygen
#会在OUTPUT_DIRECTORY所指定的路径下生成html文件夹和latex文件夹。点击index.html，在浏览器
#就会看到生成的文档。

/**< 如果希望生成CHM文档 -- 需要单独在window下进行 */
SEARCHENGINE = NO
GENERATE_TREEVIEW = NO
GENERATE_HTMLHELP = YES
CHM_FILE = "test.chm"  //指定输出文件名
/** 在linux下执行doxygen，doxygen生成三个额外的HTML索引文件：
index.hhp，index.hhc，和index.hhk。这index.hhp是一个项目文件
，可以在Windows上通过Microsoft的HTML Help Workshop阅读和编译生成。*/

doxygen注释

/**常用的类型命令*/
@struct to document a C-struct. 
@union to document a union.
@enum to document an enumeration type.
@fn to document a function.
@var to document a variable or typedef or enum value.
@def to document a #defifine.
@typedef to document a type defifinition.
@file to document a fifile.
----------------------------------------------------------------------
@warning  //添加一些警告信息，使用中需要注意的地方，比如线程不安全
@return  // 用来说明函数的返回值
@author  // 作者
@version // 版本号
@date    // 日期
@exception //函数抛异常 

注：
/**< 每条注释最好以“.”结尾，最后一个注释可以不需要添加“.”*/
/**< 注释块中的参数可以使用\a进行斜体标注*/
/**< 一定要确保头文件和源文件对于同一个函数的注释要一致*/

/**函数注释格式*/
/*************************************************************************//**
* @fn void *memcpy(void *dest, const void *src, register size_t n).
* @brief Copies bytes from a source memory area to a destination memory area,
* where both areas may not overlap.
* @param[out] dest The memory area to copy to.
* @param[in] src The memory area to copy from.
* @param[in] n The number of bytes to copy.
* @return null
*****************************************************************************/
void *memcpy(void *dest, const void *src, register size_t n);

/** 文件注释格式*/
/*************************************************************************//**
* @file     	string.h
* @brief		字符串头文件
* @author 		logread
* @date    		2019-06-20
* @version  	1.0.0
* @copyright 	Copyright(C), 2017, xx xx xx xx info&tech Co., Ltd.
*****************************************************************************/

/** 宏定义注释格式 */
/*************************************************************************//**
* @def MAX(a,b)
* @brief A macro that returns the maximum of \a a and \a b.
*****************************************************************************/
#define MAX(a,b) ((a)<(b)?(b):(a))

/** 类型定义注释格式 */
/*************************************************************************//**
* @typedef typedef unsigned int UINT32
* @brief A type definition for \a unsigned \a int
*****************************************************************************/
typedef unsigned int UINT32;

/** 变量定义注释格式 */
/*************************************************************************//**
* @var int errno.
* @brief Contains the last error code.
* @warning Not thread safe!
*****************************************************************************/
int errno;

/** 枚举类型注释格式*/
/*************************************************************************//**
* @enum weekday
* @brief A enum definition for \a weekday
*****************************************************************************/
enum weekday 
{
	sun,	/**< 周日 */
	mon,	/**< 周一 */
	tue,	/**< 周二 */
	wed,	/**< 周三 */
	thu,	/**< 周四 */
	fri,	/**< 周五 */
	sat		/**< 周六 */
};

/** 结构体注释*/
这里有必要插入doxygen预处理的内容，对于doxygen输入的源文件，可以通过doxygen的内置C预处理器
进行解析。
默认情况下，doxygen仅进行部分预处理，只执行条件编译和宏定义，并不会进行宏扩展。
例如：
#define VERSION 200
#define CONST_STRING const char *

#if VERSION >= 200
  static CONST_STRING version = "2.xx";
#else
  static CONST_STRING version = "1.xx";
#endif

然后默认情况下，doxygen会将一下内容提供给解析器：
#define VERSION
#define CONST_STRING
static CONST_STRING version = "2.xx";

当禁用所有的预处理时，即ENABLE_PREPROCESSING=NO，结果会是： 
  static CONST_STRING version =“2.xx”; 
  static CONST_STRING version =“1.xx”;
被传给了解析器； 

如果希望把CONST_STRING进行宏展开，则需要将MACRO_EXPANSION=YES，然后结果会是：
#define VERSION
#define CONST_STRING

  static const char * version = "2.xx";
被传给了解析器；
此时这种设置将会展开所有的宏（在某些情况下还会进行递归展开），这就太多了。因此，doxygen允许
我们指定需要展开的宏，其余的不进行展开。此时需要设置EXPAND_ONLY_PREDEF=YES，并由标签
PREDEFINED指定宏定义。

一个典型的例子：
对于含有__attribute__ ((packed))的结构体，需要对Doxfile添加以下配置：
ENABLE_PREPROCESSING   = YES 
MACRO_EXPANSION        = YES 
EXPAND_ONLY_PREDEF     = YES 
PREDEFINED             = __attribute__(x)=

注：
PREDEFINED             = __attribute__(x)= //其实是将__attribute__(x)展开为空。
//一般操作比如：PREDEFINED  ="ASSERT(x)=assert(x)"


/*************************************************************************//**
* @struct can_msg_s
* @brief A struct definition for \a can_msg_s 
*****************************************************************************/
struct can_msg_s
{
    uint32_t msgid;                                     /**< CAN消息ID */
    uint8_t len;                                        /**< CAN消息长度 */
    uint8_t data[8];                                    /**< CAN消息数据 */
}__attribute__ ((packed));