Doxygen Param Evaluations

This serves as an overview of all potential parameters for doxygen, which are normally configured via the Doxygen.in-file. Every parameter is paired with an evaluation of whether it makes sense to have it be configurable by the user and why.

Notes:

possible/default values are sometimes not given for unsupported parameters
Boolean values in the Doxyfile.in are set with strings of "YES"/"NO", rather than True/False
When no other explanation is given, the parameter is probably a useful feature to the user and has low/no potential for causing problems

Project related configuration options

Parameter	Doxygen?	Sphinx?	Value	Default	Description	Explanation
DOXYFILE_ENCODING	No	No	-	UTF-8	Encoding of Doxyfile.in (Doxygen configuration file)	User has no contact with Doxyfile.in and other encoding could cause problems with some string variables.
PROJECT_NAME	Yes (required)	Yes (required)	str	-	Project Title used all over the generated documentation	The default value "My Project" would get confusing fast for multiple projects. Also, this is used for determining the project path when none is given.
PROJECT_NUMBER	Yes	Yes	str	None	Project version/revision number
PROJECT_BRIEF	Yes	Yes	str	None	One-line/short description of the project
PROJECT_LOGO	Yes	Yes	Path	None	Path to project logo or icon (max 200x55px) for use within documentation
PROJECT_ICON	Yes	Yes	Path	None	Path to project icon for use in the tabs
OUTPUT_DIRECTORY	No (for simplicity)	No (for simplicity)	-	*	Path to which generated documentation is written	Freely user-configurable output paths could break the toolchain and would likely require significant "defensive measures" with the toolchain.
CREATE_SUBDIRS	No	No	bool	NO	Distribute documentation output across multiple directories to potentially improve file system performance	Subdirectories would likely complicate post processing by later parts of the toolchain.
CREATE_SUBDIRS_LEVEL	No	No	-	-	Number of levels of subdirectories generated	We do not support subdirectories.
ALLOW_UNICODE_NAMES	No	No	bool	NO	Allow non-ASCII characters in file names (will be escaped otherwhise)	Reduce potential for unexpected errors caused by something this insignificant and thus improve file system support of documentation output.
OUTPUT_LANGUAGE	Yes	Yes	str	English	Language used for all constant output within documentation.
BRIEF_MEMBER_DESC	Yes	No? (probably does nothing here)	bool	YES	Include brief member descriptions after the members listed in file/class documentation (similar to Javadoc)
REPEAT_BRIEF	Yes	No? (probably does nothing here)	bool	YES	Repeat the brief description of member/function before detailed description
ABBREVIATE_BRIEF	No	No (probably does nothing here)	list[str]	it's complicated	Automatically abbreviate brief descrition	Probably too complicated for what it is worth and could potentially cause unexpected problems with certain inputs.
ALWAYS_DETAILED_SEC	Yes	No? (probably does nothing here)	bool	NO	When REPEAT_BRIEF enabled, generate detailed section even when only brief exists
INLINE_INHERITED_MEMB	Yes	Yes? (may not do anything)	bool	NO	Show inherited members as members of child class
FULL_PATH_NAMES	Yes	Yes? (may not do anything)	bool	YES	Files are referenced by their full (relative?) path instead of just the shortest possible unique path
STRIP_FROM_PATH	No	No	Path	None	Shorten full path by this given path / only display file paths starting from after this given path	This will be handled automatically, but user can still disable FULL_PATH_NAMES.
STRIP_FROM_INC_PATH	No	No	Path	None	Shorten include paths in documentation by this given path	Could probably cause issues in such a generalized scenario.
SHORT_NAMES	No	No	bool	NO	Shorten file names to support file systems with file/directory name length restrictions (DOS etc.)	People (should) have moved on from file systems, where this is necessary. (Note, that this is only about where the documentation should be stored)
JAVADOC_AUTOBRIEF	No	No	bool	NO	Interpret first line (until first dot) of Javadoc-style comment as brief without explicitly requiring a @brief tag	This is probably better handled by the docstring converter.
JAVADOC_BANNER	No	No	bool	NO*	Enable to interpret lines like /******... as beginning of Javadoc-style comment banner, instead of ignoring them	We may want this set to YES by default / always on.
QT_AUTOBRIEF	No	No	bool	NO	Interpret first line (until first dot) of Qt-style comment as brief without explicitly requiring a @brief tag	This is probably better handled by the docstring converter.
MULTILINE_CPP_IS_BRIEF	No	No	bool	No	Interpret multi-line C++ special block comments (//! or ///) as brief instead of detailed descrition	Set to NO, this likely works as we intend it to.
PYTHON_DOCSTRING	No	No	bool	YES	Treat Python docstrings as preformatted text and ignore Doxygen special commands within them as a trade-off.	Set to YES, this likely works as we intend it to.
INHERIT_DOCS	No	No	bool	YES	Undocumented members inherit documentation of the members they re-implement (if applicable)	Set to YES, this likely works as we intend it to.
SEPARATE_MEMBER_PAGES	Yes?	No (probably does nothing here)	bool	NO	Split members of files/classes/namespaces into separate pages.	Not 100% sure, if this is unproblematic for later tools. Note: Members are separated by default when using exhale.
TAB_SIZE	Yes	No? (probably does nothing here)	int	4	Number of spaces to replace tabs in code snippets with
ALIASES	No	No	list[str]?	None	Add user-defined doxygen commands	Probably too complicated for what it is worth and could potentially cause unexpected problems with certain inputs.
OPTIMIZE_OUTPUT_FOR_C	Yes	No? (probably does nothing here)	bool	NO	Change some terminology to be more tailored to C (not C++), omit list of all members, etc.	May cause problems with Sphinx later.
OPTIMIZE_OUTPUT_JAVA	No	No	bool	NO	Change output to be more tailored to Java (namespaces = packages etc.)	We do not plan to support Java.
OPTIMIZE_FOR_FORTRAN	No	No	bool	NO	Change output to be more tailored to Fortran	We do not plan to support Fortran.
OPTIMIZE_OUTPUT_VHDL	No	No	bool	NO	Change output to be more tailored to VHDL	We do not plan to support VHDL.
OPTIMIZE_OUTPUT_SLICE	No	No	bool	NO	Change output to be more tailored to Slice	We do not plan to support Slice.
EXTENSION_MAPPING	No	No	list[str]?	None	Change mapping of language parser used per file extension (format: "ext=language")	We may want to default to using "no_extension=md"
MARKDOWN_SUPPORT	No	No	bool	YES	Look for markdown formatting in all comments	We want this to stay enabled, as it should not hurt and is likely beneficial (in case there is intentional or unintentional markdown in docstrings).
TOC_INCLUDE_HEADINGS	Yes	No? (probably does nothing here)	int	5	If MARKDOWN_SUPPORT is enabled, all headers up to this level are included in table of contents
MARKDOWN_ID_STYLE	Yes	No? (probably does nothing here)	str	DOXYGEN	Specify algorithm for generating markdown heading IDs (DOXYGEN or GITHUB)	There likely is a good reason why there is a GITHUB option.
AUTOLINK_SUPPORT	No?	No? (probably does nothing here)	bool	YES	Enable to automaticaly link potentially corresponding words to classes, namespaces, etc. (except they start with '%')	Probably overall helpful, but might occasionally cause some confusion when the links are wrong.
BUILTIN_STL_SUPPORT	No	No	bool	NO	Enable to automatically match STL classes (std::string, std::vector.) (also benefits inheritance/collaboration diagrams)	We may want this to be True by default, because it is unlikely such a tag file exists, when there is no proper documentation in the first place.
CPP_CLI_SUPPORT	No?	No?	bool	NO	If you use Microsoft's C++/CLI language, you should set this option to YES to enable parsing support. (a bit unclear)	Probably does nothing here.
SIP_SUPPORT	Yes?	Yes?	bool	NO	If whole project consists of SIP (Python bindings for C generator), enable to to use public inheritance when not explicitly protected.	Requires some additional knowledge from the user, but "not enabling by accident" should not cause much harm.
IDL_PROPERTY_SUPPORT	Yes	Yes	bool	YES	If Microsoft IDL is present, use properties for getters/setters where applicable	Judging from being enabled by default, this does not cause harm even when Microsoft IDL is not used. Option to disable given anyway.
DISTRIBUTE_GROUP_DOC	No	No	bool	NO	If member grouping is used, use documentation of first grouß members for the other members as well	The way it is described, this could unintentionally overwrite documentation of group members that are not the first.
GROUP_NESTED_COMPOUNDS	Yes?	Yes?	bool	NO	Enable to automatically add nested structs/classes to group when "parent" is added (otherwise \ingroup is required)	Seems really niche.
SUBGROUPING	Yes?	Yes?	bool	YES	Enable to allow class member groups of the same type (i. e. group of public functions) (can be disabled per class by \nosubgrouping)	Seems really niche.
INLINE_GROUPED_CLASSES	Yes?	No? (probably does nothing here)	bool	NO	Enable to show group members inside group they are included instead of on separate pages (does not work with SEPARATE_MEMBER_PAGES)	Seems really niche.
INLINE_SIMPLE_STRUCTS	Yes?	No? (probably does nothing here)	bool	NO	Enable to inline structs/classes only containing typedefs and public data fields to page of their parent class/namespace	Seems really niche.
TYPEDEF_HIDES_STRUCT	Yes	Yes?	bool	NO	Enable to refer to typedefed struct/uniion/enum by name of typedef instead of listing typedefs as members
LOOKUP_CACHE_SIZE	No	No	int	0	Specify size of lookup cache for types/symbols (2^(16+LOOKUP_CACHE_SIZE))	User likely can not guess how many different types/symbols will be encountered. Default should be way higher, as memory is not that sparse these days. However, a flag for "small cache" could be added as a safety measure.
NUM_PROC_THREADS	No	No	int	1	Specify number of threads doxygen is allowed to use for input processing (use DOT_NUM_THREADS for specifying threads for dot graph generation)	We want this set to 0 to automatically determine the number of threads based on processor cores
TIMESTAMP	Yes	No? (probably does nothing here)	str	NO	Specify whether and how to add timestamp to each page (YES, NO, DATETIME or DATE) (relevant when trying to compare output of multiple runs)	Only allow [DATETIME, DATE, NO] and default to DATETIME (more traceability by default for safety reasons)

Build related configuration options

Parameter	Doxygen?	Sphinx?	Value	Default	Description	Explanation
EXTRACT_ALL	No	No	bool	NO	Enable to extract all entities whether documented or not (except privat/static)	We want this to be True.
EXTRACT_PRIVATE	Yes	Yes	bool	NO	Enable to include private members in documentation	We want this to be True by default.
EXTRACT_PRIV_VIRTUAL	Yes	Yes	bool	No	Enable to include private virtual methods in documentation	We want this to be True by default.
EXTRACT_PACKAGE	Yes	Yes	bool	No	Enable to include members with package or internal scope in documentation	We want this to be True by default.
EXTRACT_STATIC	Yes	Yes	bool	No	Enable to include static members of files in documentation	We want this to be True by default.
EXTRACT_LOCAL_CLASSES	Yes	Yes	bool	No	Enable to include locally defined structs/classes in documentation (not for Java)	We want this to be True by default.
EXTRACT_LOCAL_METHODS	No	No	bool	No	Enable to include locally defined methods in documentation (only Objective-C)	We do not support Objective-C.
EXTRACT_ANON_NSPACES	Yes	Yes	bool	No	Enable to include members of anonymous namespaces in documentation	We want this to be True by default.
RESOLVE_UNNAMED_PARAMS	No	No	bool	YES	Enable to derive names of unnamed parameters by corresponding definition	We want this to be True.
HIDE_UNDOC_MEMBERS	No	No	bool	NO	Enable to hide undocumented members (not in overview, only documentaion)	Overwritten by EXTRACT_ALL = True.
HIDE_UNDOC_CLASSES	No	No	bool	NO	Enable to hide undocumented classes (not in overview, only documentaion)	Overwritten by EXTRACT_ALL = True.
HIDE_FRIEND_COMPOUNDS	No?	No?	bool	NO	Enable to hide friend declarations	We (probably) want this to be True.
HIDE_IN_BODY_DOCS	No	No	bool	NO	Enable to hide documentation blocks inside function body (otherwise, they are appended)
INTERNAL_DOCS	No	No	bool	NO	Enable to include documentation after \internal comment	We want this to be True.
CASE_SENSE_NAMES	No	No	str	SYSTEM	Set case sensitivity for output files	This is about the system the docs are generated on.
HIDE_SCOPE_NAMES	Yes	Yes?	bool	NO	Enable to hide full class and namescape scopes in documentaiton
HIDE_COMPOUND_REFERENCE	Yes	No?	bool	NO	Enable to hide class reference etc. on documentation pages
SHOW_HEADERFILE	Yes	No?	bool	YES	Enable to show which header file to include to use a class
SHOW_INCLUDE_FILES	Yes	No?	bool	YES	Enable to show which files a file includes in its documentation
SHOW_GROUPED_MEMB_INC	Yes	No?	bool	NO	Enable to show which file to include to use a group member
FORCE_LOCAL_INCLUDES
INLINE_INFO
SORT_MEMBER_DOCS
SORT_BRIEF_DOCS
SORT_MEMBERS_CTORS_1ST
SORT_GROUP_NAMES
SORT_BY_SCOPE_NAME
STRICT_PROTO_MATCHING
GENERATE_TODOLIST
GENERATE_TESTLIST
GENERATE_BUGLIST
GENERATE_DEPRECATEDLIST
ENABLED_SECTIONS
MAX_INITIALIZER_LINES
SHOW_USED_FILES
SHOW_FILES
SHOW_NAMESPACES
FILE_VERSION_FILTER
LAYOUT_FILE
CITE_BIB_FILES

Configuration options related to warning and progress messages

Parameter	Doxygen?	Sphinx?	Value	Default	Description	Explanation
QUIET	No	No	bool	NO	Enable to turn off messages in console	It makes more sense to add option to disable logging for the whole toolchain.
WARNINGS	Yes	Yes	bool	YES	Enable to generate warning messages to stderr	Should be called "disable_doxygen_warnings".
WARN_IF_UNDOCUMENTED	No	No	bool	-	Enable to generate warnings for undocumented members	Overwritten by EXTRACT_ALL = True.
WARN_IF_DOC_ERROR	No	No	bool	YES	Enable to generate warnings for potential documentation errors (duplicates, nonexisting, wrong markup, etc.)	We want this to be True (to simplify) and there are probably no cases where this has to be disabled.
WARN_IF_INCOMPLETE_DOC	No	No	bool	NO	Enable to generate warnings when function parameter documentation is incomplete	We want this to be True (to simplify) and there are probably no cases where this has to be disabled.
WARN_NO_PARAMDOC	No	No	bool	NO	Enable to generate warnings when function documentation is missing parameters or return value	Automatically disabled by EXTRACT_ALL = True.
WARN_IF_UNDOC_ENUM_VAL	No	No	bool	NO	Enable to generate warnings when enum values are not documented	Automatically disabled by EXTRACT_ALL = True.
WARN_AS_ERROR	No	No	bool	NO	Enable to stop doxygen execution immediately when a warning is encountered	Depending on the "safety level" it could be a requirement to reject software with undocumented components. However, enabling this would likely stop doxygen before doing much of anything, when not disabling all "ifs".
WARN_FORMAT	No	No	str	-	Specify text format of warning messages	Default format should be sufficient for locating errors, if desired. After all, fixing the documentation is not really a use case for us.
WARN_LINE_FORMAT	No	No	str	-	Specify custom cut/paste-string for jumping to error locations	Default format should be sufficient for locating errors, if desired. After all, fixing the documentation is not really a use case for us.
WARN_LOGFILE	No	No	Path	None	Path to write logfile of doxygen warnings/errors	This should be handled by us rater than the user.

Configuration options related to the input files

Parameter	Doxygen?	Sphinx?	Value	Default	Description	Explanation
INPUT	Yes	Yes	Path	-	Path to files/directories containing a project's documented source files	We default to a Path constructed from the project name, but also want to offer the option to overwrite it with a custom path, when provided.
INPUT_ENCODING	Yes	Yes	str	UTF-8	Expected chracter encoding of the source files (output will be UTF-8, see https://www.gnu.org/software/libiconv/ for possible input encodings)	There may be cases, where there is no way around the user trying out different encodings, UNLESS we want to implement some kind of auto-detection.
INPUT_FILE_ENCODING	Yes	Yes	list[str]	None	List of patterns to specify encodings for individual (groups of) files (pattern=encoding (like *.php=ISO-8859-1))	Potentially too complicated for the user's intentions, but may be necessary in some cases, UNLESS we want to implement some kind of file-level auto-detection.
FILE_PATTERNS	No	No	list[str]	...	List of patterns (like .h, .hpp, etc.) to classify files within INPUT as relevant	Default should already contain extensions of all supported relevant file types. We may add ".txt" to not miss documentation of some "off standard C code" etc.
RECURSIVE	No	No	bool	NO	Enable to parse subdirectories of INPUT as well	We want this to be True.
EXCLUDE	No	No	Path	None	Path to files/directories that should explicitely NOT be included in the documentation	Not really applicable for a user that doesn't know the project.
EXCLUDE_SYMLINKS	Yes	Yes	bool	NO	Enable to exclude files that are symlinks from the documentation
EXCLUDE_PATTERNS	No	No	list[str]	None	List of wildcard patterns (e. g. /test/) to exclude files from	Not really applicable for a user that doesn't know the project.
EXCLUDE_SYMBOLS	No	No	list[str]	None	List of symbol names to exclude from documentation	Not really applicable for a user that doesn't know the project.
EXAMPLE_PATH	No	No	Path	None	Path to files or directories containing example code fragments	We want to operate on a "one directory per project"-basis. If the examples are within the project directory, they should already be included.
EXAMPLE_PATTERNS	No	No	list[str]	None	List of patterns (like .h, .hpp, etc.) to classify files within EXAMPLE_PATH as relevant	We do not use EXAMPLE_PATH.
EXAMPLE_RECURSIVE	No	No	bool	NO	Enable to parse subdirectories of EXAMPLE_PATH as well	We do not use EXAMPLE_PATH.
IMAGE_PATH
INPUT_FILTER
FILTER_PATTERNS
FILTER_SOURCE_FILES
FILTER_SOURCE_PATTERNS
USE_MDFILE_AS_MAINPAGE	No	No? (likely does nothing)	Path	None	Name of a markdown file to incorporate into the main page (index.html)	We may want the Readme file to be referenced here, but this will require a search for a top level ".md" or .txt" titled something like "Readme".
FORTRAN_COMMENT_AFTER	No	No	int	72	Number of characters after which a line of Fortran is automatically considered as a comment	We do not support fortran.

Configuration options related to source browsing

Parameter	Doxygen?	Sphinx?	Value	Default	Description	Explanation
SOURCE_BROWSER	Yes	Yes? (might do nothing)	bool	NO	Enable to generate list of source files to cross-reference in documentation	Could be combined with VERBATIM_HEADERS for a "no source code" option. As this is tailored for use with already open-source software, we may want this True by default and necessity of this as an option is debatable.
INLINE_SOURCES	Yes	Yes? (might do nothing)	bool	NO	Enable to inline function bodies, macros, enums or list initialized variables directly into documentation
STRIP_CODE_COMMENTS	Yes	Yes? (might do nothing)	bool	YES	Enable to remove "special command blocks" from source code fragments in documentation
REFERENCED_BY_RELATION	Yes	Yes? (might do nothing)	bool	NO	Enable to list all documented functions referencing it for each documented entity	We may want this to be true by default.
REFERENCES_RELATION	Yes	Yes? (might do nothing)	bool	NO	Enable to list all documented entities called/used for each documented function	We may want this to be true by default.
REFERENCES_LINK_SOURCE			bool	YES
SOURCE_TOOLTIPS
USE_HTAGS
VERBATIM_HEADERS
CLANG_ASSISTED_PARSING
CLANG_ADD_INC_PATHS
CLANG_OPTIONS
CLANG_DATABASE_PATH

Configuration options related to the alphabetical class index

Parameter	Doxygen?	Sphinx?	Value	Default	Description	Explanation
ALPHABETICAL_INDEX	No	No	bool	YES	Enable to generate alphabetical index of all compounds	We want this to be True.
IGNORE_PREFIX	No	No	list	None	Provide certain prefixes to cause compounds to not appear in alphabetical index	Too convoluted/complicated and potentially unpredictably error-prone.