Doxygen + Sphinx +呼吸+呼气

问题描述 投票:0回答:1

目前,我正在研究项目文档。当我在conf.py中包含源文件和头文件时,HTML成功生成。但是,当我只想将源文件用于文档HTML文件时,就出了点问题。如以下,

enter image description here

我的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

  1. @ cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT
  2. / * @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表示对我有好处。enter image description here

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

enter image description here

对于这些工具,我是陌生的,如果有愚蠢的问题或信息不足,请告诉我。非常感谢。

python-sphinx doxygen
1个回答
0
投票

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

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

© www.soinside.com 2019 - 2024. All rights reserved.