Doxyfile 1.12.0 Translation

原创

已于 2024-10-13 13:19:49 修改 · 置顶 · 458 阅读

4 ·

CC 4.0 BY-SA版权

文章标签：

#Doxygen #CangJie Doc

于 2024-10-06 10:23:14 首次发布

00 Overall

#----------------------------------------
# Doxyfile 1.12.0 Doxygen www.doxygen.org
#----------------------------------------

# 注释：single hash (#)
# 标签(tag)注释： double hash (##)

# format：
# TAG = value [value, ...]

# for list：append item as follow：
# TAG += value [value, ...]

# 包含空格(space)的值(value)，应放在引号之间(between quote(\" \"))；

# 将使用的配置文件与模板配置文件比较：doxygen -x [configFile]

# 将使用的配置文件与模板配置文件比较，而不替换环境变量或CMake类型替换变量：
# environment variable or CMake type replacement variable：
# doxygen -x_noenv [configFile]

01 Project

#---------------
# Project Option
#---------------

# Doxyfile编码：指定配置文件中所有字符的编码，默认值：UTF-8；
# Doxygen用libiconv(或libc内置的iconv)转码(transcoding)
# https://www.gnu.org/software/libiconv
DOXYFILE_ENCODING      = UTF-8

# 项目名称：值是单词(word)，或引号(double-quote)括起来的单词序列
# (word sequence)，除非使用Doxywizard，默认值："My Project"；
PROJECT_NAME           = "My Project"

# 项目编号：用于版本控制系统或revision num，默认值：留空；
PROJECT_NUMBER         =

# 项目简述：为出现在每页顶部的项目提供可选的单行描述，
# 并应让观众快速了解项目的目的，保持描述简短，默认值：留空；

# optional one line description，at top of each page，
# give viewer quick idea，purpose，keep description short；
PROJECT_BRIEF          =

# 项目徽标：指定文档的logo或icon，默认值：留空；
# 最大高度：55px，最大宽度：200px，后续章节可修改；
PROJECT_LOGO           =

# 项目图标：指定在显示Html文档时包含在tab选项卡中的图标，默认值：留空；
PROJECT_ICON           =

# 文档输出的根目录：指定生成文档写入的相对或绝对路径，默认值：留空；
# 若输入相对路径，将与Doxygen的start位置有关，若留空，则使用当前目录；
OUTPUT_DIRECTORY       =

# 创建子目录：默认值：NO；

# YES：则Doxygen将在每种输出格式的输出目录下创建多达4096
# 个子目录(分2个level)，并将生成的文件分发到这些目录上；

# 当向Doxygen提供大量源文件时很有用，否则将所有生成的文件放在同一目录中
# 会导致文件系统的性能问题，调整CREATE_SUBDIRS_LEVEL以控制子目录的数量；
CREATE_SUBDIRS         = NO

# 创建子目录的层级：控制当CREATE_SUBDIRS为YES时将创建的子目录的数量；
# 值范围：0 ~ 8，默认值：8，先决条件：CREATE_SUBDIRS = YES；

# 级别0：16个目录，每增加一级，目录数量会翻倍，目录层级为8时目录数为4096，
# 这是默认值，也是最大值，子目录分两级，第一级总是固定的16个目录；
CREATE_SUBDIRS_LEVEL   = 8

# 允许Unicode名称：默认值：NO；
# YES：Doxygen将允许非Ascii字符出现在生成的文件名中；
# NO：则非Ascii字符将被转义，如_xE3_x81_x84将用于Unicode U+3044；
ALLOW_UNICODE_NAMES    = NO

# 输出语言：指定Doxygen生成的所有文档的编写语言，可选值如：English(默认)，Chinese；
OUTPUT_LANGUAGE        = English

# 简短的成员描述：默认值：YES；NO：禁用此功能；
# YES：Doxygen将在文件和类文档中列出的成员后包含简短的成员描述，类似于Javadoc；
BRIEF_MEMBER_DESC      = YES

# 重复简述：默认值：YES；
# YES：Doxygen将在详细描述之前(prepend)添加成员或函数的简要描述；

# prepend brief description of member 
# or function before detail description

# 注：若HIDE_UNDOC_MEMBERS和BRIEF_MEMBER_DESC都为NO，
# 则简要描述将被完全抑制(completely suppress)；
REPEAT_BRIEF           = YES

# 简述缩写：实现在各种列表中形成文本的准智能简短描述缩写器；
# implement quasi-intelligent brief description 
# abbreviator that used to form text in various listing

# 若发现此列表中的每个字符串是简要描述的前导(leading)文本，则将从文本中
# 删除/剥离(strip)，处理整个列表后的结果将用作注解(annotate)文本；

# 否则，将按原样(as-is)使用简要描述，若留空，则使用以下值：
# $name将自动替换为实体的名称，entity：类，接口，枚举，属性，方法等；

# $name class，$name widget，$name file，is，provides，
# specifies，contains，represents，a，an and .；
ABBREVIATE_BRIEF       = "The $name class" \
                         "The $name widget" \
                         "The $name file" \
                         is \
                         provides \
                         specifies \
                         contains \
                         represents \
                         a \
                         an \
                         the

# 通常详细描述章节：默认值：NO；
# 若ALWAYS_DETAILED_SEC和REPEAT_BRIEF均为YES，那即使只有
# brief description，Doxygen也会生成detailed section；
ALWAYS_DETAILED_SEC    = NO

# 内联继承成员：默认值：NO；
# YES：Doxygen将在该类的文档中显示该类的所有继承成员，这些成员像普通的类成员一样，
# 基类的constructor，destructor，assignment operator将不会显示；

INLINE_INHERITED_MEMB  = NO

# 全路径名称：默认值：YES；NO：将使用使文件名唯一的最短路径；
# YES：Doxygen将在文件列表和header文件中的文件名前prepend添加完整路径；
FULL_PATH_NAMES        = YES

# 从路径剥离：剥离路径的用户定义part，仅当指定的字符串之一与
# 路径的左侧部分匹配时才剥离；用于在文件列表中显示相对路径；

# 默认值：留空；先决条件：FULL_PATH_NAMES = YES；

# 留空：则运行Doxygen的目录将用作剥离的路径；
# 注：可指定相对路径或绝对路径，相对路径相对于启动Doxygen的目录；
STRIP_FROM_PATH        =

# 从包含路径剥离：剥离类文档中提到的路径的用户定义part，
# 此标签告诉读者，使用类需包含那个header文件；

# 默认值：留空；留空：则仅使用包含类定义的header文件的名称，
# 否则应使用 -I flag指定通常传递给编译器的包含路径列表；
STRIP_FROM_INC_PATH    =

# 短名称：默认值：NO；
# YES：Doxygen将生成更短(但可读性readable差)的文件名；
# 若文件系统不支持DOS，Mac，CD-ROM上的长名称，这很有用；
SHORT_NAMES            = NO

# Java文档自动简述：默认值：NO；
# YES：则Doxygen将把Javadoc样式注释的第一行(直到第一个dot)解释interpret为简要说明；
# NO：则Javadoc样式将表现像常规Qt样式注释(故需显式@brief命令进行brief description)；
JAVADOC_AUTOBRIEF      = NO

# Java文档横幅：默认值：NO；
# YES：则Doxygen会将一行(如/*****)解释(interpret)为Javadoc样式注释"banner"的开头；
# NO：Javadoc样式将表现得与常规注释一样，且不会被Doxygen解释(interpret)；
JAVADOC_BANNER         = NO

# QT自动简述：默认值：NO；
# YES：则Doxygen将把Qt样式注释的第一行(直到第一个dot)解释为brief description；
# NO：Qt样式将表现得像常规Qt样式注释(故需明确的\brief命令来进行简要说明)；
QT_AUTOBRIEF           = NO

# 多cpp简述：默认值：NO；YES：意味着不再识别(recognize)rational rose注释；
# YES：以使Doxygen将多行C++特殊注释块(即//!或///注释块)视为简要说明，
# 这曾经时默认行为，新的默认行为时将多行C++注释块视为详细描述，若喜欢旧行为，则设为YES；
MULTILINE_CPP_IS_BRIEF = NO

# Python DocStr：默认值：YES；默认：Python文档字符串显示为
# 预格式化文本(preformat text)，且无法使用Doxygen的特殊命令；
# NO：则可使用Doxygen特殊命令，且文档字符串的内容文档块显示为Doxygen文档；
PYTHON_DOCSTRING       = YES

# 继承文档：默认值：YES；
# YES：未文档化的成员将从其re-implement的任何documented member继承文档；
INHERIT_DOCS           = YES

# 分离成员页：默认值：NO；YES：则Doxygen将为每个成员生成一个新页面；
# NO：则成员的文档将成为包含它的file/class/namespace的一部分(part)；
SEPARATE_MEMBER_PAGES  = NO

# tab大小：设置制表符(tab)中的空格数(space)，值范围：1 ~ 16；默认值4；
# Doxygen使用此值将code fragment中的制表符替换为空格；
TAB_SIZE               = 4

# 别名：指定多个在文档中充当命令的别名，别名的形式为：name=value：
# 如添加"sideeffect=@par Side Effects:^^"；

# 将允许在文档中放置命令\sideeffect或@sideeffect，
# 这将导致用户定义的段落标题为"Side Effects:"；
# user-defined paragraph with heading "Side Effects:"；

# 注：不能在别名的值部分放置\n来插入换行符(在结果输出中)，可在别名的
# 值部分放置 ^^ 来插入换行符，就像原始文件中有物理换行符一样；

# 当需literal { 或 }时，在别名的值部分(part)，
# 必须通过反斜杠backslash(\)对其转义escape；

# 这可能导致与命令 \{ 和 \} 发生冲突，
# 故建议使用版本 @{ 和 @} 或使用双转义 \\{ 和 \\}；
ALIASES                =

# 优化输出C：默认值：NO；
# 若项目仅包含C源，请将OPTIMIZE_OUTPUT_FOR_C设为YES；

# 然后Doxygen将生成更适合C的输出，如使用的一些名称将有所不同，
# 所有成员的列表将被省略等，all member list omit；
OPTIMIZE_OUTPUT_FOR_C  = NO

# 优化输出Java：默认值：NO；
# 若项目仅包含Java或Python，请将OPTIMIZE_OUTPUT_JAVA设为YES；

# 然后Doxygen将生成更适合该语言的输出，
# 如namespace将作为package呈现，qualified scope将看起来不同等；
OPTIMIZE_OUTPUT_JAVA   = NO

# 为Fortran优化：默认值：NO；
# 若项目包含Fortran源头，请将OPTIMIZE_FOR_FORTRAN设为YES，
# 然后Doxygen将生成针对Fortran定制(tailor)的输出；
OPTIMIZE_FOR_FORTRAN   = NO

# 优化输出vhdl：默认值：NO；
# 若项目包含vhdl源，请将OPTIMIZE_OUTPUT_VHDL设为YES，
# 然后Doxygen将生成针对VHDL定制(tailor)的输出；
OPTIMIZE_OUTPUT_VHDL   = NO

# 优化输出切片：默认值：NO；
# 若项目仅包含Slice源，请将标签设为YES；然后Doxygen将生成更适合该语言的输出，
# 如namespace将呈现为module，type将separate into group；
OPTIMIZE_OUTPUT_SLICE  = NO

# 扩展映射：Doxygen根据其解析的文件的扩展名选择要使用的解析器，可指定要为给定
# 扩展名使用的解析器；Doxygen具有内置映射，可用此标签override或extend；

# 格式：ext=language，ext：文件扩展名；language：Doxygen支持的解析器，
# 如：IDL，Java，JavaScript，Lex，md (Markdown)，Python等；

# 注：对自定义扩展名，需设置FILE_PATTERNS，否则Doxygen不会读取文件，
# 指定no_extension时，应将*添加道 FILE_PATTERNS；

# 注：对没扩展名的文件，可使用no_extension作为placeholder；
# 另请查阅：default file extension mapping list；
EXTENSION_MAPPING      =

# Markdown支持：默认值：YES；
# YES：则Doxygen根据Markdown格式预处理所有注释，使文档更具可读性readable；
# https://daringfireball.net/projects/markdown

# markdown处理的输出由Doxygen进一步处理，故可将Doxygen、Html
# 和Xml命令与Markdown格式混合使用，仅在出现向后兼容性问题时禁用；
MARKDOWN_SUPPORT       = YES

# toc包含heading：非零值：所有达到该level的Heading都会自动包含在toc中，
# 即使它们没Id属性，注：此功能仅适应于Markdown Heading；
# 值范围：0 ~ 99，默认值：6；先决条件：MARKDOWN_SUPPORT = YES；
TOC_INCLUDE_HEADINGS   = 6

# Markdown Id样式：指定生成Markdownheading 
# identifier的algorithm。注：每个标识符都唯一；
# 默认值：DOXYGEN，先决条件：MARKDOWN_SUPPORT = YES；

# 可选值：DOXYGEN使用固定的'autotoc_md'字符串，后跟从零开始的
# 序列号(sequence num)，github使用小写版本的标题(lower case title)，
# 任何空格都用'-'替换，标点符号(punctuation character)被删除；
MARKDOWN_ID_STYLE      = DOXYGEN

# 自动链接支持：默认值：YES；NO：全局阻止此类链接；
# YES：Doxygen会尝试将与文档class或namespace相对应的word链接到其相应的文档；

# 个别情况，可通过在单词前面放置% sign来阻止此类链接；
# link can prevent in individual case by putting % sign；
AUTOLINK_SUPPORT       = YES

# 内置STL支持：默认值：NO；
# 若使用stl类(即std::string、std::vector等)，
# 但不想包含(tag file for)stl源作为输入，则应设为YES；

# 以便让Doxygen匹配参数包含stl类的函数声明和定义，
# 如func(std::string);与func(std::string) {}
# 也使涉及stl类的继承和协作图更加完整complete和准确accurate；
BUILTIN_STL_SUPPORT    = NO

# Cpp Cli支持：默认值：NO；
# 若使用微软的C++/CLI language，则应设为YES，以启用解析支持；
CPP_CLI_SUPPORT        = NO

# sip支持：若项目仅包含SIP源，请设为YES；默认值NO；
# https://www.riverbankcomputing.com/software

# Doxygen将像普通C++一样解析它们，但当不存在显式保护关键字时，
# 将假定所有类都使用公共继承而不是私有继承；

# assume all class use public instead of private 
# inheritance when no explicit protection keyword present；
SIP_SUPPORT            = NO

# idl属性支持：默认值：YES；
# 对Microsoft的IDL，有propget和propput属性来指示属性的getter和setter；
# YES：将使Doxygen用文档中的属性替换getter和setter；

# 这仅在方法确实获取或设置简单类型时才有效，若非此类情况，
# 或无论如何都想显示方法，则应将此选项设置为NO；
IDL_PROPERTY_SUPPORT   = YES

# 默认值为：NO。

# 分配组文档：若文档中使用成员分组，且此标签设为YES，则Doxygen将重用(reuse)组中
# 第一个成员的文档(若有，if any)供组中的其他成员使用，默认：组的所有成员都必须明确文档化；
DISTRIBUTE_GROUP_DOC   = NO

# 组嵌套复合项：默认值：NO；

# 若将struct或class添加到组中且启用此选项，则任何nest的class或struct
# 也会添加到同一组中，默认禁用此选项，可通过\ingroup添加嵌套复合项；
GROUP_NESTED_COMPOUNDS = NO

# 子组：默认值：YES；NO：可防止子分组，
# prevent subgrouping；可用\nosubgrouping命令按类执行此操作；

# YES：以允许将相同类型的类成员组(如一组公共函数)作为该类型的子组(如，在公共函数section下)

# allow class member group of same type(for instance 
# group of public function) to put as subgroup of 
# that type(e.g. under Public Function section)
SUBGROUPING            = YES

# 内联组类：默认值：NO；此功能不能与SEPARATE_MEMBER_PAGES合用；

# YES：struct，class，union将显示在所在的组
# (shown inside group)(使用\ingroup)，而不是显示在
# separate page(对Html和Man Page)或section(对LaTeX和Rtf)中；
INLINE_GROUPED_CLASSES = NO

# 内联简单结构：默认值NO；NO：struct，class，union将显示在
# separate page(对Html和Man Page)或section(对LaTeX和Rtf)中；

# YES：仅具有公共数据字段(public data field)或简单typedef字段的
# struct，class，union将以内联(inline)方式显示在定义它们的范围(scope)
# 的文档中(即file，namespace，group doc)，前提是此scope已文档化；
INLINE_SIMPLE_STRUCTS  = NO

# typedef隐藏struct：默认值：NO；
# YES：struct，union，enum将文档化为带有typedef名称的struct，union，enum；
# 因此typedef struct TypeS {} TypeT将再文档中显示为名称为TypeT的struct；

# 禁用时，typedef将作为file，namespace，class的member出现，
# 且struct被命名为TypeS，这对C代码很有用，因coding convention
# 规定(dictate)所有复合类型(compound)都是typedef，且只引用typedef，从不引用tag name；
TYPEDEF_HIDES_STRUCT   = NO

# 查找缓冲大小：设置符号查找缓存大小；symbol lookup cache size；
# 此缓存用于根据符号的名称和范围解析符号，resolve symbol，name，scope；

# 此过程昂贵(expensive)，且同一符号通常会在代码中出现多次，
# 故Doxygen会保留预先解析的符号缓存，
# 若缓存太小，Doxygen会变慢，若缓存太大，则浪费内存，

# 缓存大小公式：2 ^ (16 + LOOKUP_CACHE_SIZE)；
# 值范围：0 ~ 9，默认值：0，对应缓存大小：2^16=65536个symbol；
# 运行结束时，Doxygen将报告缓存使用情况并从速度角度建议最佳缓存大小；
LOOKUP_CACHE_SIZE      = 0

# 处理线程数：指定Doxygen在处理(processing)期间允许使用的线程数(thread num)；
# 值范围：0 ~ 32，默认值：1；若值大于零，以更好地控制CPU负载和处理速度间的平衡；
# 目前仍是实验性功能，1：即禁用并行处理，并行生成dot由DOT_NUM_THREADS设置；
NUM_PROC_THREADS       = 1

# 时间戳：可选值：YES、NO(默认)、DATETIME和DATE；
# 若设置不同于NO：则生成的每个页面将包含生成页面的date或datetime；
# 将其设为NO：有助于比较多次运行的输出；
TIMESTAMP              = NO

02 Build

#-------------
# Build Option
#-------------

# 抽取所有：默认值：NO；
# YES：Doxygen将假定文档中的所有实体都已文档化，即使没可用的文档；
# 注：这还将禁用在WARNINGS设置为YES时通常会生成的有关未文档化成员的警告

# 除非EXTRACT_PRIVATE和EXTRACT_STATIC设为YES，否则私有类成员
# (private class member)和静态文件成员(static file member)将被隐藏，
EXTRACT_ALL            = NO

# 抽取私有：默认值：NO；
# YES：则类的所有私有成员(private member)都将包含在文档中；
EXTRACT_PRIVATE        = NO

# 抽取私有虚拟：默认值：NO；
# YES：则类的文档化私有虚拟方法(private virtual method)将包含在文档中；
EXTRACT_PRIV_VIRTUAL   = NO

# 抽取包：默认值：NO；
# YES：则所有具有包或内部范围的成员都将包含在文档中；
# all member with package or internal scope；
EXTRACT_PACKAGE        = NO

# 抽取静态：默认值：NO；
# YES：则文件的所有静态成员(static member)都将包含在文档中
EXTRACT_STATIC         = NO

# 抽取局部类：默认值：YES；
# YES：则源文件中locally定义的class(和struct)将包含在文档中；
# NO：则仅包含在header file中定义的类，对Java source没任何影响；
EXTRACT_LOCAL_CLASSES  = YES

# 抽取局部方法：默认值：NO；此标签仅对Objective-C有用；
# YES：则在RI中定义但未在接口中定义的局部方法将包含在文档中；
# NO：则仅包含接口中的方法；
EXTRACT_LOCAL_METHODS  = NO

# 抽取匿名命名空间：默认值：NO；默认：匿名命名空间是隐藏的；
# YES：则匿名命名空间的成员将被抽取并作为名为'anonymous_namespace{file}'
# 的命名空间出现在文档中，其中file将被替换为包含匿名命名空间的文件的基本名称；
EXTRACT_ANON_NSPACES   = NO

# 解析未命名参数：默认值：YES；默认：未命名参数在输出中保持未命名状态；
# YES：则声明中未命名参数的名称将由相应的定义确定；
RESOLVE_UNNAMED_PARAMS = YES

# 隐藏未文档化成员：默认值：NO；
# NO：这些成员将包含在各种overview中，若启用EXTRACT_ALL，则此标签无效；

# YES：Doxygen将隐藏已文档化的类或文件内所有未文档化的成员；
# hide all undocument member inside document cls or file；
HIDE_UNDOC_MEMBERS     = NO

# 隐藏未文档化类：默认值：NO；NO：这些类将包含在各种overview中；
# 若启用，此选项还将隐藏未文档化的C++概念，若已启用EXTRACT_ALL，则标签无效；

# YES：Doxygen将隐藏类层次结构中通常可见的所有未文档化的类；
# hide all undocument cls normally visible in cls hierarchy；
HIDE_UNDOC_CLASSES     = NO

# 隐藏友好声明：默认值：NO；NO：这些声明将包含在文档中；
# YES：Doxygen将隐藏所有友好声明；hide all friend declaration；
HIDE_FRIEND_COMPOUNDS  = NO

# 隐藏函数体文档：默认值：NO；
# YES：隐藏函数主体内的任何文档块；
# NO：这些块将append到函数的详细(detail)文档块中；
HIDE_IN_BODY_DOCS      = NO

# 内部文档：是否包括在\internal命令后输入(type)的文档；
# NO：则将排除文档；YES：包括内部文档；默认值：NO；
INTERNAL_DOCS          = NO

# 正确设置CASE_SENSE_NAMES，Doxygen将更好匹配底层文件系统的功能；
# 可选值：SYSTEM(默认)、NO和YES；

# 若文件系统区分大小写(即它支持同一目录中名称仅在大小写上不同的文件)，
# 则必须将选项设置为YES 才能正确处理此类文件(若它们出现在输入中)；

# 对不区分大小写的文件系统，应设为NO，以正确处理为仅在大小写上不同的
# 符号编写(symbol write)的输出文件，如两个类，A为CLASS，B为Class，
# 且还支持对文件的引用，而无需指定完全匹配的大小写；

# 在Win(包括Cygwin)和mac上，用户通常应设为NO，
# 而在Linux或其它Unix，通常应设为YES；
CASE_SENSE_NAMES       = SYSTEM

# 隐藏名称范围：默认值：NO；YES：则范围将被隐藏；
# NO：则Doxygen将在文档中显示成员及其完整的类和命名空间范围；
# show member with their full cls and namespace scope in doc；
HIDE_SCOPE_NAMES       = NO