Regression in v4.29.0: Unparseable C cross-reference: '[out]'

[StrikerRUS]

Hi!

The following code

# c_api.h

/*!
 * \brief Load dataset from file (like LightGBM CLI version does).
 * \param filename The name of the file
 * \param parameters Additional parameters
 * \param reference Used to align bin mapper with other dataset, nullptr means isn't used
 * \param[out] out A loaded dataset
 * \return 0 when succeed, -1 when failure happens
 */
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);

#  C-API.rst

C API
=====

.. doxygenfile:: c_api.h

results in error

Warning, treated as error:
/home/runner/work/LightGBM/LightGBM/docs/C-API.rst:2:Unparseable C cross-reference: '[out]'
Invalid C declaration: Expected identifier in nested name. [error at 0]
  [out]
  ^
make: *** [Makefile:20: html] Error 2

breathe config:

    extensions.extend([
        'breathe',
    ])
    breathe_projects = {
        "LightGBM": os.path.join(CURR_PATH, 'doxyoutput', 'xml')
    }
    breathe_default_project = "LightGBM"
    breathe_domain_by_extension = {
        "h": "c",
    }
    breathe_show_define_initializer = True
    c_id_attributes = ['LIGHTGBM_C_EXPORT']

Doxygen invocation:

    input = os.path.join(CURR_PATH, os.path.pardir, 'include', 'LightGBM', 'c_api.h')
    doxygen_args = [
        f"INPUT={input}",
        f"OUTPUT_DIRECTORY={os.path.join(CURR_PATH, 'doxyoutput')}",
        "GENERATE_HTML=NO",
        "GENERATE_LATEX=NO",
        "GENERATE_XML=YES",
        "XML_OUTPUT=xml",
        "XML_PROGRAMLISTING=YES",
        r'ALIASES="rst=\verbatim embed:rst:leading-asterisk"',
        r'ALIASES+="endrst=\endverbatim"',
        "ENABLE_PREPROCESSING=YES",
        "MACRO_EXPANSION=YES",
        "EXPAND_ONLY_PREDEF=NO",
        "SKIP_FUNCTION_MACROS=NO",
        "SORT_BRIEF_DOCS=YES",
        "WARN_AS_ERROR=YES",
    ]
    doxygen_input = '\n'.join(doxygen_args)
    doxygen_input = bytes(doxygen_input, "utf-8")
    if not os.path.exists(os.path.join(CURR_PATH, 'doxyoutput')):
        os.makedirs(os.path.join(CURR_PATH, 'doxyoutput'))
    try:
        # Warning! The following code can cause buffer overflows on RTD.
        # Consider suppressing output completely if RTD project silently fails.
        # Refer to https://github.com/svenevs/exhale
        # /blob/fe7644829057af622e467bb529db6c03a830da99/exhale/deploy.py#L99-L111
        process = Popen(["doxygen", "-"],
                        stdin=PIPE, stdout=PIPE, stderr=PIPE)
        stdout, stderr = process.communicate(doxygen_input)
        output = '\n'.join([i.decode('utf-8') for i in (stdout, stderr) if i is not None])
        if process.returncode != 0:
            raise RuntimeError(output)
        else:
            print(output)
    except BaseException as e:
        raise Exception(f"An error has occurred while executing Doxygen\n{e}")

Full reproducible project:
https://github.com/microsoft/LightGBM/tree/master/docs

Restricting breathe version: breathe<4.29 allows to generate docs without any issues.

[StrikerRUS]

Huh, when was creating the issue, I didn't see #673.

Accoring to Doxygen \param reference, there could be also [in,out] attribute, btw.

[vermeeren]

I will consider this a duplicate of #673, will make a release after checking all pending issue and patches today.