documentation/doxygen: explanatory comments for parts without CI coverage.

Also restoring the note about the cpp_function_attributes regression
test.

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 39c3a7ae42be2563d352a4d2cfc896915e989b34..8708ed86db67bfbf973902ce09659d9292496603 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -2002,9 +2002,6 @@ def parse_func(state: State, element: ET.Element):
     # First the prefix keywords - Doxygen has a habit of leaking attributes and
     # other specifiers into the function's return type, and not necessarily
     # in any consistent order (including swapping it with the actual type!)
-    #
-    # (Note that since 1.8.16 the keyword/type ordering has not been a problem,
-    # but this handling is left as a future-proofing mechanism.)
     exposed_attribute_keywords = [
         'constexpr',
         'consteval',
@@ -2028,6 +2025,10 @@ def parse_func(state: State, element: ET.Element):
             elif func.type.startswith(kw + ' '):
                 func.type = func.type[len(kw):].strip()
             elif func.type.endswith(' ' + kw):
+                # Uncovered; since 1.8.16 the keyword/type ordering (with
+                # decltype(auto), see the cpp_function_attributes test for a
+                # repro case) has not been a problem, but this handling is left
+                # as a future-proofing mechanism.
                 func.type = func.type[:len(kw)].strip()
             else:
                 continue
@@ -2045,6 +2046,8 @@ def parse_func(state: State, element: ET.Element):
     if 'constexpr' in element.attrib:
         func.is_constexpr = func.is_constexpr or element.attrib['constexpr'] == 'yes'
     if 'consteval' in element.attrib:
+        # consteval XML attribute is since Doxygen 1.9, earlier versions keep
+        # the keyword in the signature
         func.is_consteval = func.is_consteval or element.attrib['consteval'] == 'yes'
     func.prefix = ''
     if is_static: