From dd1b6f50f267975cda323641927b14771628a059 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 14 Sep 2024 19:07:03 +0200 Subject: [PATCH] documentation/doxygen: this bug with includes happens only on < 1.8.20. --- .../test_doxygen/compound_includes/Second.h | 15 +++-- .../structSpreadClass-1818.html | 67 +++++++++++++++++++ .../compound_includes/structSpreadClass.html | 23 ++----- .../structSpreadClass.html | 4 +- .../Second.h | 15 +++-- documentation/test_doxygen/test_compound.py | 8 ++- 6 files changed, 97 insertions(+), 35 deletions(-) create mode 100644 documentation/test_doxygen/compound_includes/structSpreadClass-1818.html diff --git a/documentation/test_doxygen/compound_includes/Second.h b/documentation/test_doxygen/compound_includes/Second.h index 19253104..19e646fd 100644 --- a/documentation/test_doxygen/compound_includes/Second.h +++ b/documentation/test_doxygen/compound_includes/Second.h @@ -52,15 +52,16 @@ void relatedFunc(); /** @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. +Doxygen < 1.8.20 is stupid and 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. +With Doxygen < 1.8.20, 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. With 1.8.20+, there should be just one (correct) +include for the whole class. */ template struct SpreadClass { - /** @brief A function with (detailed) include information but no details if includes are disabled */ + /** @brief A function with (detailed) include information on < 1.8.20 but no details if includes are disabled or on 1.8.20+ */ void foo(); }; diff --git a/documentation/test_doxygen/compound_includes/structSpreadClass-1818.html b/documentation/test_doxygen/compound_includes/structSpreadClass-1818.html new file mode 100644 index 00000000..b66c90f3 --- /dev/null +++ b/documentation/test_doxygen/compound_includes/structSpreadClass-1818.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.

+ +

Doxygen < 1.8.20 is stupid and 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.

With Doxygen < 1.8.20, 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. With 1.8.20+, there should be just one (correct) include for the whole class.

+
+

Public functions

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

Function documentation

+
+

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

+

A function with (detailed) include information on < 1.8.20 but no details if includes are disabled or on 1.8.20+.

+
+
+
+
+
+
+ + diff --git a/documentation/test_doxygen/compound_includes/structSpreadClass.html b/documentation/test_doxygen/compound_includes/structSpreadClass.html index 8b41f78f..249dac33 100644 --- a/documentation/test_doxygen/compound_includes/structSpreadClass.html +++ b/documentation/test_doxygen/compound_includes/structSpreadClass.html @@ -20,7 +20,7 @@

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

@@ -36,29 +36,16 @@ -

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.

+

Doxygen < 1.8.20 is stupid and 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.

With Doxygen < 1.8.20, 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. With 1.8.20+, there should be just one (correct) include for the whole class.

Public functions

-
- void foo() +
+ void foo()
-
A function with (detailed) include information but no details if includes are disabled.
+
A function with (detailed) include information on < 1.8.20 but no details if includes are disabled or on 1.8.20+.
-
-

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/structSpreadClass.html b/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html index 0863f675..b9400a0c 100644 --- a/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html +++ b/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html @@ -35,14 +35,14 @@ -

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.

+

Doxygen < 1.8.20 is stupid and 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.

With Doxygen < 1.8.20, 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. With 1.8.20+, there should be just one (correct) include for the whole class.

Public functions

void foo()
-
A function with (detailed) include information but no details if includes are disabled.
+
A function with (detailed) include information on < 1.8.20 but no details if includes are disabled or on 1.8.20+.
diff --git a/documentation/test_doxygen/compound_includes_undocumented_files/Second.h b/documentation/test_doxygen/compound_includes_undocumented_files/Second.h index bddea706..9e21f6cf 100644 --- a/documentation/test_doxygen/compound_includes_undocumented_files/Second.h +++ b/documentation/test_doxygen/compound_includes_undocumented_files/Second.h @@ -51,15 +51,16 @@ void relatedFunc(); /** @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. +Doxygen < 1.8.20 is stupid and 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. +With Doxygen < 1.8.20, 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. With 1.8.20+, there should be just one (correct) +include for the whole class. */ template struct SpreadClass { - /** @brief A function with (detailed) include information but no details if includes are disabled */ + /** @brief A function with (detailed) include information on < 1.8.20 but no details if includes are disabled or on 1.8.20+ */ void foo(); }; diff --git a/documentation/test_doxygen/test_compound.py b/documentation/test_doxygen/test_compound.py index 622c63a4..5da15447 100644 --- a/documentation/test_doxygen/test_compound.py +++ b/documentation/test_doxygen/test_compound.py @@ -270,7 +270,13 @@ class Includes(IntegrationTestCase): 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')) + + # The bug this tests for happens only on < 1.8.20. Maybe it's fixed in + # 1.8.19 already, but I only have 1.8.18 and 1.8.20 available to test. + if parse_version(doxygen_version()) >= parse_version("1.8.20"): + self.assertEqual(*self.actual_expected_contents('structSpreadClass.html')) + else: + self.assertEqual(*self.actual_expected_contents('structSpreadClass.html', 'structSpreadClass-1818.html')) # These two should all have local includes because otherwise it gets # misleading; the Empty namespace a global one -- 2.30.2