From 33c62d64c5ef50f05fd686e23e74006ab5b514f8 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 7 May 2020 19:22:09 +0200 Subject: [PATCH] documentation/doxygen: avoid useless detailed docs in some cases. If a class was spread over more files (either because of related functions or because Doxygen bugs) and SHOW_INCLUDE_FILES was disabled or the file was not documented, the detailed docs contained nothing except brief, being useless. Do not add them in that case. --- documentation/doxygen.py | 7 +- .../test_doxygen/compound_includes/Doxyfile | 3 + .../test_doxygen/compound_includes/First.h | 2 + .../test_doxygen/compound_includes/Second.h | 26 +++++-- .../compound_includes/classClass.html | 20 ++--- ...aceContainsNamespace_1_1ContainsClass.html | 2 +- .../compound_includes/namespaceSpread.html | 2 +- .../compound_includes/structSpreadClass.html | 67 +++++++++++++++++ .../compound_includes_disabled/Doxyfile | 1 + .../classClass.html | 75 ++++--------------- .../namespaceSpread.html | 2 +- .../structSpreadClass.html | 53 +++++++++++++ .../Doxyfile | 3 + .../Second.h | 26 +++++-- documentation/test_doxygen/test_compound.py | 14 +++- 15 files changed, 214 insertions(+), 89 deletions(-) create mode 100644 documentation/test_doxygen/compound_includes/structSpreadClass.html create mode 100644 documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 6bb6b8bf..975b15a3 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -222,13 +222,16 @@ def parse_id_and_include(state: State, element: ET.Element) -> Tuple[str, str, s # Extract corresponding include also for class/struct/union "relateds", if # it's different from what the class has. This also forcibly enables # has_details (unlike the case above, where has_details will be enabled - # only if all members don't have the same include) + # only if all members don't have the same include) -- however if + # SHOW_INCLUDE_FILES isn't enabled or the file is not documented, this + # would generate useless empty detailed sections so in that case it's not + # set. if state.current_kind in ['class', 'struct', 'union']: location_attribs = element.find('location').attrib file = location_attribs['declfile'] if 'declfile' in location_attribs else location_attribs['file'] if state.current_include != file: include = make_include(state, file) - has_details = True + has_details = include and state.doxyfile['SHOW_INCLUDE_FILES'] return id[:i], id[:i] + '.html', id[i+2:], include, has_details diff --git a/documentation/test_doxygen/compound_includes/Doxyfile b/documentation/test_doxygen/compound_includes/Doxyfile index 67be987c..c4eeb416 100644 --- a/documentation/test_doxygen/compound_includes/Doxyfile +++ b/documentation/test_doxygen/compound_includes/Doxyfile @@ -12,3 +12,6 @@ CASE_SENSE_NAMES = YES ##! M_LINKS_NAVBAR1 = ##! M_LINKS_NAVBAR2 = ##! M_SEARCH_DISABLED = YES + +# otherwise it links to Second.h and Union, DO NOT WANT +AUTOLINK_SUPPORT = NO diff --git a/documentation/test_doxygen/compound_includes/First.h b/documentation/test_doxygen/compound_includes/First.h index 62a48682..52d644cb 100644 --- a/documentation/test_doxygen/compound_includes/First.h +++ b/documentation/test_doxygen/compound_includes/First.h @@ -155,3 +155,5 @@ namespace ContainsNamespace { Even though it has no members that could set the global include for it. */ namespace Empty {} + +template struct SpreadClass; diff --git a/documentation/test_doxygen/compound_includes/Second.h b/documentation/test_doxygen/compound_includes/Second.h index 2fa0e554..19253104 100644 --- a/documentation/test_doxygen/compound_includes/Second.h +++ b/documentation/test_doxygen/compound_includes/Second.h @@ -23,28 +23,44 @@ enum Flag {}; */ /** @related Class - * @brief A related enum in a different file + * @brief A related enum in a different file. Detailed info only if includes not disabled. */ enum RelatedEnum {}; /** @related Class - * @brief A related typedef in a different file + * @brief A related typedef in a different file. Detailed info only if includes not disabled. */ typedef int RelatedInt; /** @related Class - * @brief A related variable in a different file + * @brief A related variable in a different file. Detailed info only if includes not disabled. */ constexpr const int RelatedVar = 3; /** @related Class - * @brief A related function in a different file + * @brief A related function in a different file. Detailed info only if includes not disabled. */ void relatedFunc(); /** @related Class - * @brief A related define in a different file + * @brief A related define in a different file. Detailed info only if includes not disabled. */ #define RELATED_DEFINE } + +/** +@brief A class forward-declared in one file but defined in another + +Because Doxygen is stupid, it reports the class to be defined in First.h even +though there's just a fwdecl. Happens only if the class is a template, +a non-templated class would have its location reported correctly. + +If includes are enabled, members should have Second.h listed as their include, +but if they are disabled, brief-only members shouldn't have detailed sections +at all. +*/ +template struct SpreadClass { + /** @brief A function with (detailed) include information but no details if includes are disabled */ + void foo(); +}; diff --git a/documentation/test_doxygen/compound_includes/classClass.html b/documentation/test_doxygen/compound_includes/classClass.html index 0a065513..1b1c5060 100644 --- a/documentation/test_doxygen/compound_includes/classClass.html +++ b/documentation/test_doxygen/compound_includes/classClass.html @@ -52,23 +52,23 @@
enum RelatedEnum { }
-
A related enum in a different file.
+
A related enum in a different file. Detailed info only if includes not disabled.
using RelatedInt = int
-
A related typedef in a different file.
+
A related typedef in a different file. Detailed info only if includes not disabled.
const int RelatedVar constexpr
-
A related variable in a different file.
+
A related variable in a different file. Detailed info only if includes not disabled.
void relatedFunc()
-
A related function in a different file.
+
A related function in a different file. Detailed info only if includes not disabled.
#define RELATED_DEFINE
-
A related define in a different file.
+
A related define in a different file. Detailed info only if includes not disabled.
@@ -78,7 +78,7 @@ enum RelatedEnum
#include <Second.h>
-

A related enum in a different file.

+

A related enum in a different file. Detailed info only if includes not disabled.

@@ -88,7 +88,7 @@ typedef int RelatedInt
#include <Second.h>
-

A related typedef in a different file.

+

A related typedef in a different file. Detailed info only if includes not disabled.

@@ -98,7 +98,7 @@ void relatedFunc()
#include <Second.h>
-

A related function in a different file.

+

A related function in a different file. Detailed info only if includes not disabled.

@@ -108,7 +108,7 @@ const int RelatedVar constexpr
#include <Second.h>
-

A related variable in a different file.

+

A related variable in a different file. Detailed info only if includes not disabled.

@@ -118,7 +118,7 @@ #define RELATED_DEFINE
#include <Second.h>
-

A related define in a different file.

+

A related define in a different file. Detailed info only if includes not disabled.

diff --git a/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html b/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html index 3f0c8d46..05203932 100644 --- a/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html +++ b/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html @@ -42,7 +42,7 @@
union Union
-
Union.
+
Union.
diff --git a/documentation/test_doxygen/compound_includes/namespaceSpread.html b/documentation/test_doxygen/compound_includes/namespaceSpread.html index 8d246f55..f92e1002 100644 --- a/documentation/test_doxygen/compound_includes/namespaceSpread.html +++ b/documentation/test_doxygen/compound_includes/namespaceSpread.html @@ -49,7 +49,7 @@
enum RelatedEnum { }
-
A related enum in a different file.
+
A related enum in a different file. Detailed info only if includes not disabled.
diff --git a/documentation/test_doxygen/compound_includes/structSpreadClass.html b/documentation/test_doxygen/compound_includes/structSpreadClass.html new file mode 100644 index 00000000..a092da7d --- /dev/null +++ b/documentation/test_doxygen/compound_includes/structSpreadClass.html @@ -0,0 +1,67 @@ + + + + + SpreadClass struct | My Project + + + + + +
+
+
+
+
+

+
#include <First.h>
+
template<class T>
+ SpreadClass struct +

+

A class forward-declared in one file but defined in another.

+
+

Contents

+ +
+

Because Doxygen is stupid, it reports the class to be defined in First.h even though there's just a fwdecl. Happens only if the class is a template, a non-templated class would have its location reported correctly.

If includes are enabled, members should have Second.h listed as their include, but if they are disabled, brief-only members shouldn't have detailed sections at all.

+
+

Public functions

+
+
+ void foo() +
+
A function with (detailed) include information but no details if includes are disabled.
+
+
+
+

Function documentation

+
+

+
#include <Second.h>
+
+ template<class T> +
+ void SpreadClass<T>::foo() +

+

A function with (detailed) include information but no details if includes are disabled.

+
+
+
+
+
+
+ + diff --git a/documentation/test_doxygen/compound_includes_disabled/Doxyfile b/documentation/test_doxygen/compound_includes_disabled/Doxyfile index d91e9802..463ec024 100644 --- a/documentation/test_doxygen/compound_includes_disabled/Doxyfile +++ b/documentation/test_doxygen/compound_includes_disabled/Doxyfile @@ -13,4 +13,5 @@ CASE_SENSE_NAMES = YES ##! M_LINKS_NAVBAR2 = ##! M_SEARCH_DISABLED = YES +AUTOLINK_SUPPORT = NO # otherwise it links to Second.h, DO NOT WANT SHOW_INCLUDE_FILES = NO # explicitly disabled diff --git a/documentation/test_doxygen/compound_includes_disabled/classClass.html b/documentation/test_doxygen/compound_includes_disabled/classClass.html index 76333961..e59bee99 100644 --- a/documentation/test_doxygen/compound_includes_disabled/classClass.html +++ b/documentation/test_doxygen/compound_includes_disabled/classClass.html @@ -48,73 +48,28 @@ -
-

Enum documentation

-
-

- enum RelatedEnum -

-

A related enum in a different file.

-
-
-
-

Typedef documentation

-
-

- typedef int RelatedInt -

-

A related typedef in a different file.

-
-
-
-

Function documentation

-
-

- void relatedFunc() -

-

A related function in a different file.

-
-
-
-

Variable documentation

-
-

- const int RelatedVar constexpr -

-

A related variable in a different file.

-
-
-
-

Define documentation

-
-

- #define RELATED_DEFINE -

-

A related define in a different file.

-
-
diff --git a/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html b/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html index 454abbfd..bcac827a 100644 --- a/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html +++ b/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html @@ -49,7 +49,7 @@
enum RelatedEnum { }
-
A related enum in a different file.
+
A related enum in a different file. Detailed info only if includes not disabled.
diff --git a/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html b/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html new file mode 100644 index 00000000..576544d9 --- /dev/null +++ b/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html @@ -0,0 +1,53 @@ + + + + + SpreadClass struct | My Project + + + + + +
+
+
+
+
+

+
template<class T>
+ SpreadClass struct +

+

A class forward-declared in one file but defined in another.

+
+

Contents

+ +
+

Because Doxygen is stupid, it reports the class to be defined in First.h even though there's just a fwdecl. Happens only if the class is a template, a non-templated class would have its location reported correctly.

If includes are enabled, members should have Second.h listed as their include, but if they are disabled, brief-only members shouldn't have detailed sections at all.

+
+

Public functions

+
+
+ void foo() +
+
A function with (detailed) include information but no details if includes are disabled.
+
+
+
+
+
+
+ + diff --git a/documentation/test_doxygen/compound_includes_undocumented_files/Doxyfile b/documentation/test_doxygen/compound_includes_undocumented_files/Doxyfile index 9d4129f9..708d36f9 100644 --- a/documentation/test_doxygen/compound_includes_undocumented_files/Doxyfile +++ b/documentation/test_doxygen/compound_includes_undocumented_files/Doxyfile @@ -6,9 +6,12 @@ GENERATE_XML = YES XML_PROGRAMLISTING = NO CASE_SENSE_NAMES = YES + ##! M_PAGE_FINE_PRINT = ##! M_THEME_COLOR = ##! M_FAVICON = ##! M_LINKS_NAVBAR1 = ##! M_LINKS_NAVBAR2 = ##! M_SEARCH_DISABLED = YES + +AUTOLINK_SUPPORT = NO # otherwise it links to Second.h, DO NOT WANT diff --git a/documentation/test_doxygen/compound_includes_undocumented_files/Second.h b/documentation/test_doxygen/compound_includes_undocumented_files/Second.h index 226242b2..bddea706 100644 --- a/documentation/test_doxygen/compound_includes_undocumented_files/Second.h +++ b/documentation/test_doxygen/compound_includes_undocumented_files/Second.h @@ -22,28 +22,44 @@ enum Flag {}; */ /** @related Class - * @brief A related enum in a different file + * @brief A related enum in a different file. Detailed info only if includes not disabled. */ enum RelatedEnum {}; /** @related Class - * @brief A related typedef in a different file + * @brief A related typedef in a different file. Detailed info only if includes not disabled. */ typedef int RelatedInt; /** @related Class - * @brief A related variable in a different file + * @brief A related variable in a different file. Detailed info only if includes not disabled. */ constexpr const int RelatedVar = 3; /** @related Class - * @brief A related function in a different file + * @brief A related function in a different file. Detailed info only if includes not disabled. */ void relatedFunc(); /** @related Class - * @brief A related define in a different file + * @brief A related define in a different file. Detailed info only if includes not disabled. */ #define RELATED_DEFINE } + +/** +@brief A class forward-declared in one file but defined in another + +Because Doxygen is stupid, it reports the class to be defined in First.h even +though there's just a fwdecl. Happens only if the class is a template, +a non-templated class would have its location reported correctly. + +If includes are enabled, members should have Second.h listed as their include, +but if they are disabled, brief-only members shouldn't have detailed sections +at all. +*/ +template struct SpreadClass { + /** @brief A function with (detailed) include information but no details if includes are disabled */ + void foo(); +}; diff --git a/documentation/test_doxygen/test_compound.py b/documentation/test_doxygen/test_compound.py index 3d15b3f9..72d7f089 100644 --- a/documentation/test_doxygen/test_compound.py +++ b/documentation/test_doxygen/test_compound.py @@ -257,11 +257,14 @@ class Includes(IntegrationTestCase): # The Contained namespace should have just the global include, the # Spread just the local includes, the class a global include and the - # group, even though in a single file, should have local includes + # group, even though in a single file, should have local includes; and + # the SpreadClass struct is forward-declared in another file, which + # triggers a silly Doxygen bug so it has per-member includes also self.assertEqual(*self.actual_expected_contents('namespaceContained.html')) self.assertEqual(*self.actual_expected_contents('namespaceSpread.html')) self.assertEqual(*self.actual_expected_contents('classClass.html')) self.assertEqual(*self.actual_expected_contents('group__group.html')) + self.assertEqual(*self.actual_expected_contents('structSpreadClass.html')) # These two should all have local includes because otherwise it gets # misleading; the Empty namespace a global one @@ -276,11 +279,13 @@ class IncludesDisabled(IntegrationTestCase): def test(self): self.run_doxygen(wildcard='*.xml') - # No include information as SHOW_INCLUDE_FILES is disabled globally + # No include information as SHOW_INCLUDE_FILES is disabled globally, + # and no useless detailed sections either self.assertEqual(*self.actual_expected_contents('namespaceContained.html')) self.assertEqual(*self.actual_expected_contents('namespaceSpread.html')) self.assertEqual(*self.actual_expected_contents('classClass.html')) self.assertEqual(*self.actual_expected_contents('group__group.html')) + self.assertEqual(*self.actual_expected_contents('structSpreadClass.html')) class IncludesUndocumentedFiles(IntegrationTestCase): def __init__(self, *args, **kwargs): @@ -290,12 +295,13 @@ class IncludesUndocumentedFiles(IntegrationTestCase): self.run_doxygen(wildcard='*.xml') # The files are not documented, so there should be no include - # information -- practically the same output as when SHOW_INCLUDE_FILES - # is disabled globally + # information and no useless detailed sections either -- practically + # the same output as when SHOW_INCLUDE_FILES is disabled globally self.assertEqual(*self.actual_expected_contents('namespaceContained.html', '../compound_includes_disabled/namespaceContained.html')) self.assertEqual(*self.actual_expected_contents('namespaceSpread.html', '../compound_includes_disabled/namespaceSpread.html')) self.assertEqual(*self.actual_expected_contents('classClass.html', '../compound_includes_disabled/classClass.html')) self.assertEqual(*self.actual_expected_contents('group__group.html', '../compound_includes_disabled/group__group.html')) + self.assertEqual(*self.actual_expected_contents('structSpreadClass.html', '../compound_includes_disabled/structSpreadClass.html')) class IncludesTemplated(IntegrationTestCase): def __init__(self, *args, **kwargs): -- 2.30.2