Doxygen + сфинкс + Дышите + Выдохните

Question

В настоящее время я работаю над проектной документацией. Когда я включаю исходный файл и заголовочный файл в 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 Обновление (UT C Время: 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;
}

Без учета @ секунды результат Doxygen выглядит следующим образом. На самом деле, в Doxygen представление мне хорошо.

Но при изменении представления Sphinx пользователь увидит две одинаковые функции и список на боковой панели без какой-либо подробной информации, чтобы различить guish it:

Я новичок в этих инструментах, если есть глупые вопросы или недостаточно информации, пожалуйста, дайте мне знать. Большое спасибо.

Answer 1

Одной из проблем является неправильное использование оператора @param с doxygen. Синтаксис \param '['dir']' <parameter-name> { parameter description }.

В вашем примере имя параметра будет Data, тогда как на самом деле параметр data. Насколько я могу догадаться, вы планируете использовать @param[in] data Data buffer.