Doxygen+狮身人面像+呼吸+呼气答案

【问题标题】：Doxygen+Sphinx+Breathe+ExhaleDoxygen+狮身人面像+呼吸+呼气
【发布时间】：2020-01-30 16:33:15
【问题描述】：

目前，我正在编写项目文档。当我在 conf.py 中包含源文件和头文件时，HTML 生成成功。但是当我只想将源文件用于文档 HTML 文件时，它就有问题了。比如下面，

我的conf.py内容如下，

# Setup the exhale extension
exhale_args = {
    # These arguments are required
    "containmentFolder":     "./api",
    "rootFileName":          "library_root.rst",
    "rootFileTitle":         "Library API",
    "doxygenStripFromPath":  "..",
    # Suggested optional arguments
    "createTreeView":        True,
    # TIP: if using the sphinx-bootstrap-theme, you need
    # "treeViewIsBootstrap": True,
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin": textwrap.dedent('''
        EXTRACT_ALL = YES
        SOURCE_BROWSER = YES
        EXTRACT_STATIC = YES
        OPTIMIZE_OUTPUT_FOR_C  = YES
        HIDE_SCOPE_NAMES = YES
        QUIET = YES
        INPUT = ../include ../src
        FILE_PATTERNS = *.c *.h
        EXAMPLE_RECURSIVE = YES
        GENERATE_TREEVIEW = YES
    ''')
}

成功结果的源文件和头文件

[源文件]

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

[头文件]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

失败结果的源文件和头文件

[源文件]

/**
 * @brief Fills the data buffer
 * @param[in] Data buffer
 * @return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

[头文件]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

// char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

我可以使用没有头文件的 Doxygen 来生成我想要的结果。非常感谢。

2020.01.31 更新（UTC 时间：02:51）

由于文档重复，我想在头文件中添加以下注释。 http://doxygen.10944.n7.nabble.com/Remove-detailed-documentation-from-header-td3679.html

@cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT
/* @endcond */

[头文件]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif
/* @cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT */
char* at_test_action(void* data);
/* @endcond */

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

[源文件]

/**
 * \brief Fills the data buffer
 * \param[in] data data buffer for content preparation
 * \return pointer to the data buffer
 **/
char* at_test_action(void* data)
{
    char* ptr = (char*) data;

    sprintf( ptr, "AT\r\n" );

    return ptr;
}

没有上述@cond，Doxygen 结果如下。实际上，在 Doxygen 中表示对我有好处。

但是当更改为 Sphinx 表示时，用户将看到两个相同的功能并在侧边栏列出，没有任何详细信息来区分它：

我是这些工具的新手，如果有愚蠢的问题或信息不足，请告诉我。非常感谢。

【问题讨论】：

为什么要注释掉原型？您使用的是哪个 doxygen 版本？问题可能来自后处理 Sphinx 等，这可能要求当包含文件存在时它应该包含原型。
为什么要注释掉原型？因为我要处理重复的文档，所以我会添加 INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT 如上面的更新。您使用的是哪个 doxygen 版本？ 1.8.16 非常感谢。
在更新的问题中写道：“但是当更改为 Sphinx 表示时，用户将看到两个相同的功能并在侧边栏中列出，没有任何详细信息来区分它”，所以，对我来说，实际上是 Sphinx没有正确输出数据。
是的，但我认为当我排除头文件时，源文件注释应该正确输出。但我不知道为什么我不能得到好结果。

标签： python-sphinx doxygen

【解决方案1】：

一个问题是@param 语句与 doxygen 的错误使用。语法是\param '['dir']' <parameter-name> { parameter description }。

在您的示例中，参数名称为Data，而实际上参数为data。据我所知，您的预期用途是@param[in] data Data buffer。

【讨论】：