欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识！
您现在的位置是： 首页

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

程序员文章站 2024-03-20 22:23:46
...

Doxygen简介

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

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

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

 

 

 

 

 

相关标签： 代码注释 API文档 Linux

上一篇： 微服务架构

下一篇： java导出excel文件

推荐阅读