Doxygen+Sphinx+Breathe+Exhale

Question

Currently, I am working on project documentation. When I include source file and header file in conf.py the HTML generated successfully. But when I want to use source file only to documentation HTML file, there has something wrong on it. Such as following,

My conf.py content as below,

# 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
    ''')
}

The source file and header file with success result

[Source File]

/**
 * @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;
}

[Header File]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

The source file and header file with fail result

[Source File]

/**
 * @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;
}

[Header File]

#ifndef TEST_H
#define TEST_H

#ifdef __cplusplus
extern "C" {
#endif

// char* at_test_action(void* data);

#ifdef __cplusplus
}
#endif

#endif /* TEST_H */

And I can use Doxygen without header file to generate result which I want. Thank you very much.

2020.01.31 Update (UTC Time: 02:51)

Because of duplicate documentation, I want to add below comment into header file. http://doxygen.10944.n7.nabble.com/Remove-detailed-documentation-from-header-td3679.html

@cond INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT
/* @endcond */

[Header File]

#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 */

[Source File]

/**
 * \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;
}

Without above @cond the Doxygen result as following. Actually, in Doxygen representation is good for me.

But when change to Sphinx representation, user will see two same functions and list at sidebar without any detail information to distinguish it:

I am new for those tools, if there has stupid questions or the information is not enough, please let me know. Thank you very much.

Why do you comment out the prototype? Which doxygen version are you using? Problem might come from the postprocessing Sphinx etc. that maybe requires that when an include file is present it should contain the prototype. — albert
Why do you comment out the prototype? <Griffith> Because I want to deal with duplicate documentation, so I will add INCLUDE_THIS_SECTION_IN_DOXYGEN_OUTPUT such as above update. Which doxygen version are you using? <Griffith> 1.8.16 Thank you very much. — Griffith Chen
In the updated question it is written: "But when change to Sphinx representation, user will see two same functions and list at sidebar without any detail information to distinguish it", so, to me, actually Sphinx does noy output the data correctly. — albert
Yes, but I think that when I exclude header file, the source file comment should output correctly. But I am not sure why I cannot get good result. — Griffith Chen

albert albert · Accepted Answer · 2020-01-30T17:13:16

One problem is the incorrect usage of the @param statement with doxygen. The syntax is \param '['dir']' <parameter-name> { parameter description }.

In your example the parameter name would be Data whilst the parameter in fact is data. As far as I can guess your intended use is @param[in] data Data buffer.

Doxygen+Sphinx+Breathe+Exhale

1 Answers