doxygen 常见问题一览表(中文乱码等)

doxygen 常见问题一览表(中文乱码等)

Doxygen是一个用于自动生成文档的工具，可以从代码中提取注释，并生成HTML和LaTeX格式的文档。在使用Doxygen的过程中，常常会遇到一些问题，下面列出常见问题及解决方法。

中文乱码问题

在生成文档时，如果出现了中文乱码，可能的原因有：

1. 源代码文件使用了错误的编码格式（如GB2312）；
2. 未设置正确的输入和输出编码格式；
3. Doxygen本身没有正确的支持中文。

解决方法：

1. 将源代码文件的编码格式转换为UTF-8或者ANSI格式，以确保后续的操作都在正确的编码格式下进行。
2. 在Doxygen的配置文件中，设置输入和输出编码格式，如下所示：

INPUT_ENCODING = UTF-8
OUTPUT_ENCODING = UTF-8

1. 在Doxygen的配置文件中，启用UTF-8支持，如下所示：

USE_UNICODE = YES
UTF8_SUPPORT = YES

Doxygen无法处理C++11特性问题

Doxygen默认无法处理一些C++11语言特性的文档，如智能指针（std::shared_ptr）等。

解决方法：

在Doxygen的配置文件中，将ENABLE_PREPROCESSING, MACRO_EXPANSION等选项设置为YES，并且设置EXPAND_ONLY_PREDEF为YES，使用Doxygen的预处理器来提取C++11语言特性的文档。

ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES

示例说明1

以下是一份配置文件示例，包含了上面提到的解决中文乱码问题和Doxygen不能处理C++11特性的问题的配置：

# Configuration options related to the input files
INPUT                  = ./src
FILE_PATTERNS          = *.h \
                         *.cpp
RECURSIVE              = YES

# Configuration options related to the source code
ENABLE_PREPROCESSING   = YES
MACRO_EXPANSION        = YES
EXPAND_ONLY_PREDEF     = YES
PREDEFINED             = __cplusplus=201103L

# Configuration options related to the output format
GENERATE_HTML          = YES
HTML_OUTPUT            = ./docs
HTML_FILE_EXTENSION    = .html
HTML_COLORSTYLE_HUE    = 220
HTML_COLORSTYLE_SAT    = 100
HTML_COLORSTYLE_GAMMA  = 80
HTML_TIMESTAMP         = YES
OUTPUT_DIRECTORY       = .
OUTPUT_LANGUAGE        = English
USE_WINDOWS_ENCODING   = NO
BUILTIN_STL_SUPPORT    = YES

# Configuration options related to the input encoding format
INPUT_ENCODING         = UTF-8
OUTPUT_ENCODING        = UTF-8
USE_UNICODE            = YES
UTF8_SUPPORT           = YES

示例说明2

以下是使用Doxygen的预处理器解决Doxygen不能处理C++11特性的文档时，定义一个宏来隐藏C++11特性的示例：

/*! \def DOXYGEN_SKIP_MACRO_PARSING
 *  \brief 宏定义可用于隐藏不支持的C++11特性。
 *
 *  Doxygen不能正常处理一些C++11特性，例如智能指针和lambda表达式。如果需要在
 *  注释中使用这些特性的代码示例，可以使用宏定义来隐藏这些特性。
 */
#if __cplusplus >= 201103L
#  define DOXYGEN_SKIP_MACRO_PARSING
#endif

/*! \class Foo
 *  \brief 封装了一个整形和一个智能指针。
 *
 *  这是一个使用C++11特性的封装类，不使用宏的情况下，Doxygen将无法处理这个类。
 *  使用DOXYGEN_SKIP_MACRO_PARSING宏定义即可隐藏这些代码块。
 */
class Foo {
public:
#if defined(DOXYGEN_SKIP_MACRO_PARSING)
    // 智能指针在Doxygen中不能正常处理，使用宏隐藏
    typedef std::shared_ptr<int> int_ptr_t;
#else
    typedef int* int_ptr_t;
#endif

    Foo(int value) : value_(value) {
#if !defined(DOXYGEN_SKIP_MACRO_PARSING)
        ptr_ = new int(value);
#endif
    }

    ~Foo() {
#if !defined(DOXYGEN_SKIP_MACRO_PARSING)
        delete ptr_;
#endif
    }

private:
    int value_;
#if defined(DOXYGEN_SKIP_MACRO_PARSING)
    // 智能指针在Doxygen中不能正常处理，使用宏隐藏
    int_ptr_t ptr_;
#else
    std::shared_ptr<int> ptr_;
#endif
};