documentation/doxygen: add support for class-specific location.

When documenting a class, a struct or an union, Doxygen allows the user
to specify a custom header.

Doxygen doc:
  \class <name> [<header-file>] [<header-name>]
  \struct <name> [<header-file>] [<header-name>]
  \union <name> [<header-file>] [<header-name>]

The specified <header-name> can be retrieved between the
<includes></includes> tag of the generated xml for the
classes/structs/unions constructs.

This patch uses <header-name> instead of the default path extracted from
the <location file="xx"/> without modifying the location.

This also fixes #137 for these three constructs when the user does not
define the <header-file>/<header-name>, because the value present inside
the <includes> tag is stripped using the Doxygen STRIP_FROM_INC_PATH
option, whereas <location file="xx"/> is not. Hence, there is still an
issue for namespaces, free functions, enums, typedefs, variables and
defines which are not part of a class/struct or union.

Co-authored-by: Vladimír Vondruš <mosra@centrum.cz>

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index e6ed6202d7dae407ce8532841c77ec0b77fdd310..5a17deb1b25930920bc25a9f3d523f8a740ca825 100755 (executable)
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -260,9 +260,12 @@ def parse_ref(state: State, element: ET.Element, add_inline_css_class: str = Non
 
     return '<a href="{}" class="{}">{}</a>'.format(url, class_, add_wbr(parse_inline_desc(state, element).strip()))
 
-def make_include(state: State, file) -> Tuple[str, str]:
+def make_include(state: State, file, include_str=None) -> Tuple[str, str]:
+    if include_str is None:
+        include_str = file
+
     if file in state.includes and state.compounds[state.includes[file]].has_details:
-        return (html.escape('<{}>'.format(file)), state.compounds[state.includes[file]].url)
+        return (html.escape('<{}>'.format(include_str)), state.compounds[state.includes[file]].url)
     return None
 
 def parse_id_and_include(state: State, element: ET.Element) -> Tuple[str, str, str, Tuple[str, str], bool]:
@@ -2861,7 +2864,8 @@ def parse_xml(state: State, xml: str):
     if compound.kind in ['struct', 'class', 'union'] or (compound.kind == 'namespace' and compounddef.find('innerclass') is None and compounddef.find('innernamespace') is None and compounddef.find('sectiondef') is None):
         location_attribs = compounddef.find('location').attrib
         file = location_attribs['declfile'] if 'declfile' in location_attribs else location_attribs['file']
-        compound.include = make_include(state, file)
+        include_str = compounddef.find('includes').text if compounddef.find('includes') is not None else file
+        compound.include = make_include(state, file, include_str)
 
         # Save include for current compound. Every enum/var/function/... parser
         # checks against it and resets to None in case the include differs for