Functions are not found in groups with doxygen 1.9.8

[danlkv]

Summary

.. doxygenfunction:: myFunction fails when Doxygen lists the function under a file compound in index.xml but the function’s refid points to a group__... compound.

Versions:

• Doxygen 1.9.8
• Sphinx 8.2.3
• Breathe 4.36.0
• Ubuntu 24.04

This uses Doxygen’s “grouping markers” (@{ / @}) as described in the Doxygen manual.

Reproducer

include/mylib.h:

/** \defgroup myapi My API */
/** @{ */
/** \brief A function in a group. */
int myFunction(int* handle);
/** @} */

Doxyfile:

PROJECT_NAME           = "breathe-doxygen-refid-group-repro"
INPUT                  = include/mylib.h
GENERATE_HTML          = NO
GENERATE_LATEX         = NO
GENERATE_XML           = YES
XML_OUTPUT             = xml

sphinx/conf.py:

extensions = ["breathe"]
breathe_projects = {"repro": "../xml"}
breathe_default_project = "repro"

sphinx/index.rst:

.. doxygenfunction:: myFunction

Commands

python3 -m pip install --user -U virtualenv
python3 -m virtualenv .venv
. .venv/bin/activate
python -m pip install -U pip
python -m pip install "sphinx==8.2.3" "breathe==4.36.0"

rm -rf xml
doxygen --version
doxygen Doxyfile

sphinx-build -b html -E -a -W --keep-going sphinx _build/html

What Doxygen produces (key snippet)

xml/index.xml:

<compound refid="mylib_8h" kind="file"><name>mylib.h</name>
  <member refid="group__myapi_1gab05f9132a5a9cbdc9a13d810c384464d" kind="function"><name>myFunction</name></member>
</compound>

Failure

sphinx/index.rst:1: WARNING: doxygenfunction: Cannot find function "myFunction" in doxygen xml output for project "repro" from directory: ../xml [docutils]

[danlkv]

LLM-generated patch (gpt-5.2):

diff --git a/breathe/finder/index.py b/breathe/finder/index.py
index 0c3c3f1..f2a1a7b 100644
--- a/breathe/finder/index.py
+++ b/breathe/finder/index.py
@@ -60,12 +60,35 @@ class CompoundTypeSubItemFinder(ItemFinder):
             finder = self.item_finder_factory.create_finder(file_data)

             for member_stack in member_matches:
                 ref_filter = self.filter_factory.create_id_filter(
                     "memberdef", member_stack[0].refid
                 )
-                finder.filter_(node_stack, ref_filter, matches)
+                local_matches = []
+                finder.filter_(node_stack, ref_filter, local_matches)
+
+                # Doxygen can emit index <member> entries under one compound (e.g., a file),
+                # but point refid at a different compound's memberdef (e.g., a group). In that
+                # case, the memberdef won't be found in the current compound xml.
+                #
+                # Doxygen memberdef ids commonly have the form "<compound_refid>_1<hash...>".
+                # If the direct lookup fails, try deriving the compound refid from the member id.
+                if not local_matches:
+                    refid = member_stack[0].refid
+                    compound_refid = refid.split("_1", 1)[0]
+                    if compound_refid and compound_refid != self.data_object.refid:
+                        try:
+                            alt_file_data = self.compound_parser.parse(compound_refid)
+                        except Exception:
+                            alt_file_data = None
+                        if alt_file_data is not None:
+                            alt_finder = self.item_finder_factory.create_finder(alt_file_data)
+                            alt_finder.filter_(node_stack, ref_filter, local_matches)
+
+                matches.extend(local_matches)
         else:
             # Read in the xml file referenced by the compound and descend into that as well
             file_data = self.compound_parser.parse(self.data_object.refid)
             finder = self.item_finder_factory.create_finder(file_data)
             finder.filter_(node_stack, filter_, matches)