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.

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 6bb6b8bf1818ad43cfcd3bab44229f22fb996c0f..975b15a3c723e2045cd8e9f68d194ebc20877820 100755 (executable)
--- 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 67be987c0d71612ccef455a8b66fee79d7176215..c4eeb416bc282a5a3e684a7ab9d9d7ccd7b4d673 100644 (file)
--- 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 62a4868258f33d2daecc594b19ee52fc1f28aaed..52d644cb601fbc77719e7fd8541401767dee57ef 100644 (file)
--- 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 <typename> struct SpreadClass;

diff --git a/documentation/test_doxygen/compound_includes/Second.h b/documentation/test_doxygen/compound_includes/Second.h
index 2fa0e554c8438c10845aa0d834b54c032202eb3e..19253104b61007903318002225d01e9733588215 100644 (file)
--- 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<class T> 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 0a065513b4223795f96b665dfcfa38ff06970726..1b1c5060092901fef2332fe84ed32032fbb7e3e6 100644 (file)
--- a/documentation/test_doxygen/compound_includes/classClass.html
+++ b/documentation/test_doxygen/compound_includes/classClass.html
@@ -52,23 +52,23 @@
             <dt>
               <span class="m-doc-wrap-bumper">enum <a href="#ab66c81fc768958c4185a517d488a89c7" class="m-doc">RelatedEnum</a> { </span><span class="m-doc-wrap"> }</span>
             </dt>
-            <dd>A related enum in a different file.</dd>
+            <dd>A related enum in a different file. Detailed info only if includes not disabled.</dd>
             <dt>
               using <a href="#aca8f196c01494bf1dab261745f3693c8" class="m-doc">RelatedInt</a> = int
             </dt>
-            <dd>A related typedef in a different file.</dd>
+            <dd>A related typedef in a different file. Detailed info only if includes not disabled.</dd>
             <dt>
               const int <a href="#a15e320413819ae46dffcbccbbb542b8c" class="m-doc">RelatedVar</a> <span class="m-label m-flat m-primary">constexpr</span>
             </dt>
-            <dd>A related variable in a different file.</dd>
+            <dd>A related variable in a different file. Detailed info only if includes not disabled.</dd>
             <dt>
               <span class="m-doc-wrap-bumper">void <a href="#a8b69414d6ef13f920d3a855bd22362fb" class="m-doc">relatedFunc</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
-            <dd>A related function in a different file.</dd>
+            <dd>A related function in a different file. Detailed info only if includes not disabled.</dd>
             <dt>
               <span class="m-doc-wrap-bumper">#define <a href="#a8887c0b6a87e2438ea90ffe476680da1" class="m-doc">RELATED_DEFINE</a></span>
             </dt>
-            <dd>A related define in a different file.</dd>
+            <dd>A related define in a different file. Detailed info only if includes not disabled.</dd>
           </dl>
         </section>
         <section>
@@ -78,7 +78,7 @@
               enum <a href="#ab66c81fc768958c4185a517d488a89c7" class="m-doc-self">RelatedEnum</a>
               <div class="m-doc-include m-code m-inverted m-text-right"><span class="cp">#include</span> <a class="cpf" href="Second_8h.html">&lt;Second.h&gt;</a></div>
             </h3>
-            <p>A related enum in a different file.</p>
+            <p>A related enum in a different file. Detailed info only if includes not disabled.</p>
           </div></section>
         </section>
         <section>
@@ -88,7 +88,7 @@
               typedef int <a href="#aca8f196c01494bf1dab261745f3693c8" class="m-doc-self">RelatedInt</a>
               <div class="m-doc-include m-code m-inverted m-text-right"><span class="cp">#include</span> <a class="cpf" href="Second_8h.html">&lt;Second.h&gt;</a></div>
             </h3>
-            <p>A related typedef in a different file.</p>
+            <p>A related typedef in a different file. Detailed info only if includes not disabled.</p>
           </div></section>
         </section>
         <section>
@@ -98,7 +98,7 @@
               <span class="m-doc-wrap-bumper">void </span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#a8b69414d6ef13f920d3a855bd22362fb" class="m-doc-self">relatedFunc</a>(</span><span class="m-doc-wrap">)</span></span>
               <div class="m-doc-include m-code m-inverted m-text-right"><span class="cp">#include</span> <a class="cpf" href="Second_8h.html">&lt;Second.h&gt;</a></div>
             </h3>
-            <p>A related function in a different file.</p>
+            <p>A related function in a different file. Detailed info only if includes not disabled.</p>
           </div></section>
         </section>
         <section>
@@ -108,7 +108,7 @@
               const int <a href="#a15e320413819ae46dffcbccbbb542b8c" class="m-doc-self">RelatedVar</a> <span class="m-label m-primary">constexpr</span>
               <div class="m-doc-include m-code m-inverted m-text-right"><span class="cp">#include</span> <a class="cpf" href="Second_8h.html">&lt;Second.h&gt;</a></div>
             </h3>
-            <p>A related variable in a different file.</p>
+            <p>A related variable in a different file. Detailed info only if includes not disabled.</p>
           </div></section>
         </section>
         <section>
@@ -118,7 +118,7 @@
               <span class="m-doc-wrap-bumper">#define <a href="#a8887c0b6a87e2438ea90ffe476680da1" class="m-doc-self">RELATED_DEFINE</a></span>
               <div class="m-doc-include m-code m-inverted m-text-right"><span class="cp">#include</span> <a class="cpf" href="Second_8h.html">&lt;Second.h&gt;</a></div>
             </h3>
-            <p>A related define in a different file.</p>
+            <p>A related define in a different file. Detailed info only if includes not disabled.</p>
           </div></section>
         </section>
       </div>

diff --git a/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html b/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html
index 3f0c8d46f9fc6e1f6b324eb7b747ec1b578e9091..052039329e9ecfaaf7fb8ecc70ac87570fc94b76 100644 (file)
--- a/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html
+++ b/documentation/test_doxygen/compound_includes/namespaceContainsNamespace_1_1ContainsClass.html
@@ -42,7 +42,7 @@
             <dt>
               union <a href="unionContainsNamespace_1_1ContainsClass_1_1Union.html" class="m-doc">Union</a>
             </dt>
-            <dd><a href="unionContainsNamespace_1_1ContainsClass_1_1Union.html" class="m-doc">Union</a>.</dd>
+            <dd>Union.</dd>
           </dl>
         </section>
         <section id="func-members">

diff --git a/documentation/test_doxygen/compound_includes/namespaceSpread.html b/documentation/test_doxygen/compound_includes/namespaceSpread.html
index 8d246f55e8927fed559aceecdfa37944e1e72fe4..f92e10028b6d29f78d3ad052af651aa399c2bc3d 100644 (file)
--- a/documentation/test_doxygen/compound_includes/namespaceSpread.html
+++ b/documentation/test_doxygen/compound_includes/namespaceSpread.html
@@ -49,7 +49,7 @@
             <dt>
               <span class="m-doc-wrap-bumper">enum <a href="classClass.html#ab66c81fc768958c4185a517d488a89c7" class="m-doc">RelatedEnum</a> { </span><span class="m-doc-wrap"> }</span>
             </dt>
-            <dd>A related enum in a different file.</dd>
+            <dd>A related enum in a different file. Detailed info only if includes not disabled.</dd>
           </dl>
         </section>
         <section id="typedef-members">

diff --git a/documentation/test_doxygen/compound_includes/structSpreadClass.html b/documentation/test_doxygen/compound_includes/structSpreadClass.html
new file mode 100644 (file)
index 0000000..a092da7
--- /dev/null
+++ b/documentation/test_doxygen/compound_includes/structSpreadClass.html
@@ -0,0 +1,67 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>SpreadClass struct | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          <div class="m-doc-include m-code m-inverted m-right-m m-text-right"><span class="cp">#include</span> <a class="cpf" href="First_8h.html">&lt;First.h&gt;</a></div>
+          <div class="m-doc-template">template&lt;class T&gt;</div>
+          SpreadClass <span class="m-thin">struct</span>
+        </h1>
+        <p>A class forward-declared in one file but defined in another.</p>
+        <div class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#pub-methods">Public functions</a></li>
+              </ul>
+            </li>
+          </ul>
+        </div>
+<p>Because Doxygen is stupid, it reports the class to be defined in First.h even though there&#x27;s just a fwdecl. Happens only if the class is a template, a non-templated class would have its location reported correctly.</p><p>If includes are enabled, members should have Second.h listed as their include, but if they are disabled, brief-only members shouldn&#x27;t have detailed sections at all.</p>
+        <section id="pub-methods">
+          <h2><a href="#pub-methods">Public functions</a></h2>
+          <dl class="m-doc">
+            <dt>
+              <span class="m-doc-wrap-bumper">void <a href="#a0537e4d57c78086a29ab6143da0d9a21" class="m-doc">foo</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd>A function with (detailed) include information but no details if includes are disabled.</dd>
+          </dl>
+        </section>
+        <section>
+          <h2>Function documentation</h2>
+          <section class="m-doc-details" id="a0537e4d57c78086a29ab6143da0d9a21"><div>
+            <h3>
+              <div class="m-doc-include m-code m-inverted m-right-m m-text-right"><span class="cp">#include</span> <a class="cpf" href="Second_8h.html">&lt;Second.h&gt;</a></div>
+              <div class="m-doc-template">
+                template&lt;class T&gt;
+              </div>
+              <span class="m-doc-wrap-bumper">void SpreadClass&lt;T&gt;::<wbr /></span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#a0537e4d57c78086a29ab6143da0d9a21" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">)</span></span>
+            </h3>
+            <p>A function with (detailed) include information but no details if includes are disabled.</p>
+          </div></section>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/documentation/test_doxygen/compound_includes_disabled/Doxyfile b/documentation/test_doxygen/compound_includes_disabled/Doxyfile
index d91e9802fdb087682238845ba92748d64d4cd389..463ec024828fdf7052bab61b18012e15f5d26756 100644 (file)
--- 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 763339614026f2c270d5c839c41312ecb8fc19ea..e59bee9960ec790c2c5a8f39edcd0f0d21ccc529 100644 (file)
--- a/documentation/test_doxygen/compound_includes_disabled/classClass.html
+++ b/documentation/test_doxygen/compound_includes_disabled/classClass.html
@@ -48,73 +48,28 @@
         <section id="related">
           <h2><a href="#related">Related</a></h2>
           <dl class="m-doc">
-            <dt>
-              <span class="m-doc-wrap-bumper">enum <a href="#ab66c81fc768958c4185a517d488a89c7" class="m-doc">RelatedEnum</a> { </span><span class="m-doc-wrap"> }</span>
+            <dt id="ab66c81fc768958c4185a517d488a89c7">
+              <span class="m-doc-wrap-bumper">enum <a href="#ab66c81fc768958c4185a517d488a89c7" class="m-doc-self">RelatedEnum</a> { </span><span class="m-doc-wrap"> }</span>
             </dt>
-            <dd>A related enum in a different file.</dd>
-            <dt>
-              using <a href="#aca8f196c01494bf1dab261745f3693c8" class="m-doc">RelatedInt</a> = int
+            <dd>A related enum in a different file. Detailed info only if includes not disabled.</dd>
+            <dt id="aca8f196c01494bf1dab261745f3693c8">
+              using <a href="#aca8f196c01494bf1dab261745f3693c8" class="m-doc-self">RelatedInt</a> = int
             </dt>
-            <dd>A related typedef in a different file.</dd>
-            <dt>
-              const int <a href="#a15e320413819ae46dffcbccbbb542b8c" class="m-doc">RelatedVar</a> <span class="m-label m-flat m-primary">constexpr</span>
+            <dd>A related typedef in a different file. Detailed info only if includes not disabled.</dd>
+            <dt id="a15e320413819ae46dffcbccbbb542b8c">
+              const int <a href="#a15e320413819ae46dffcbccbbb542b8c" class="m-doc-self">RelatedVar</a> <span class="m-label m-flat m-primary">constexpr</span>
             </dt>
-            <dd>A related variable in a different file.</dd>
-            <dt>
-              <span class="m-doc-wrap-bumper">void <a href="#a8b69414d6ef13f920d3a855bd22362fb" class="m-doc">relatedFunc</a>(</span><span class="m-doc-wrap">)</span>
+            <dd>A related variable in a different file. Detailed info only if includes not disabled.</dd>
+            <dt id="a8b69414d6ef13f920d3a855bd22362fb">
+              <span class="m-doc-wrap-bumper">void <a href="#a8b69414d6ef13f920d3a855bd22362fb" class="m-doc-self">relatedFunc</a>(</span><span class="m-doc-wrap">)</span>
             </dt>
-            <dd>A related function in a different file.</dd>
-            <dt>
-              <span class="m-doc-wrap-bumper">#define <a href="#a8887c0b6a87e2438ea90ffe476680da1" class="m-doc">RELATED_DEFINE</a></span>
+            <dd>A related function in a different file. Detailed info only if includes not disabled.</dd>
+            <dt id="a8887c0b6a87e2438ea90ffe476680da1">
+              <span class="m-doc-wrap-bumper">#define <a href="#a8887c0b6a87e2438ea90ffe476680da1" class="m-doc-self">RELATED_DEFINE</a></span>
             </dt>
-            <dd>A related define in a different file.</dd>
+            <dd>A related define in a different file. Detailed info only if includes not disabled.</dd>
           </dl>
         </section>
-        <section>
-          <h2>Enum documentation</h2>
-          <section class="m-doc-details" id="ab66c81fc768958c4185a517d488a89c7"><div>
-            <h3>
-              enum <a href="#ab66c81fc768958c4185a517d488a89c7" class="m-doc-self">RelatedEnum</a>
-            </h3>
-            <p>A related enum in a different file.</p>
-          </div></section>
-        </section>
-        <section>
-          <h2>Typedef documentation</h2>
-          <section class="m-doc-details" id="aca8f196c01494bf1dab261745f3693c8"><div>
-            <h3>
-              typedef int <a href="#aca8f196c01494bf1dab261745f3693c8" class="m-doc-self">RelatedInt</a>
-            </h3>
-            <p>A related typedef in a different file.</p>
-          </div></section>
-        </section>
-        <section>
-          <h2>Function documentation</h2>
-          <section class="m-doc-details" id="a8b69414d6ef13f920d3a855bd22362fb"><div>
-            <h3>
-              <span class="m-doc-wrap-bumper">void </span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#a8b69414d6ef13f920d3a855bd22362fb" class="m-doc-self">relatedFunc</a>(</span><span class="m-doc-wrap">)</span></span>
-            </h3>
-            <p>A related function in a different file.</p>
-          </div></section>
-        </section>
-        <section>
-          <h2>Variable documentation</h2>
-          <section class="m-doc-details" id="a15e320413819ae46dffcbccbbb542b8c"><div>
-            <h3>
-              const int <a href="#a15e320413819ae46dffcbccbbb542b8c" class="m-doc-self">RelatedVar</a> <span class="m-label m-primary">constexpr</span>
-            </h3>
-            <p>A related variable in a different file.</p>
-          </div></section>
-        </section>
-        <section>
-          <h2>Define documentation</h2>
-          <section class="m-doc-details" id="a8887c0b6a87e2438ea90ffe476680da1"><div>
-            <h3>
-              <span class="m-doc-wrap-bumper">#define <a href="#a8887c0b6a87e2438ea90ffe476680da1" class="m-doc-self">RELATED_DEFINE</a></span>
-            </h3>
-            <p>A related define in a different file.</p>
-          </div></section>
-        </section>
       </div>
     </div>
   </div>

diff --git a/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html b/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html
index 454abbfd9cfc08efadfc229f4899d069d7790111..bcac827a06a1cd478a87b9d0ee8ddcac9c17a8b9 100644 (file)
--- a/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html
+++ b/documentation/test_doxygen/compound_includes_disabled/namespaceSpread.html
@@ -49,7 +49,7 @@
             <dt>
               <span class="m-doc-wrap-bumper">enum <a href="classClass.html#ab66c81fc768958c4185a517d488a89c7" class="m-doc">RelatedEnum</a> { </span><span class="m-doc-wrap"> }</span>
             </dt>
-            <dd>A related enum in a different file.</dd>
+            <dd>A related enum in a different file. Detailed info only if includes not disabled.</dd>
           </dl>
         </section>
         <section id="typedef-members">

diff --git a/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html b/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html
new file mode 100644 (file)
index 0000000..576544d
--- /dev/null
+++ b/documentation/test_doxygen/compound_includes_disabled/structSpreadClass.html
@@ -0,0 +1,53 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>SpreadClass struct | My Project</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Source+Sans+Pro:400,400i,600,600i%7CSource+Code+Pro:400,400i,600" />
+  <link rel="stylesheet" href="m-dark+documentation.compiled.css" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+</head>
+<body>
+<header><nav id="navigation">
+  <div class="m-container">
+    <div class="m-row">
+      <a href="index.html" id="m-navbar-brand" class="m-col-t-8 m-col-m-none m-left-m">My Project</a>
+    </div>
+  </div>
+</nav></header>
+<main><article>
+  <div class="m-container m-container-inflatable">
+    <div class="m-row">
+      <div class="m-col-l-10 m-push-l-1">
+        <h1>
+          <div class="m-doc-template">template&lt;class T&gt;</div>
+          SpreadClass <span class="m-thin">struct</span>
+        </h1>
+        <p>A class forward-declared in one file but defined in another.</p>
+        <div class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#pub-methods">Public functions</a></li>
+              </ul>
+            </li>
+          </ul>
+        </div>
+<p>Because Doxygen is stupid, it reports the class to be defined in First.h even though there&#x27;s just a fwdecl. Happens only if the class is a template, a non-templated class would have its location reported correctly.</p><p>If includes are enabled, members should have Second.h listed as their include, but if they are disabled, brief-only members shouldn&#x27;t have detailed sections at all.</p>
+        <section id="pub-methods">
+          <h2><a href="#pub-methods">Public functions</a></h2>
+          <dl class="m-doc">
+            <dt id="a0537e4d57c78086a29ab6143da0d9a21">
+              <span class="m-doc-wrap-bumper">void <a href="#a0537e4d57c78086a29ab6143da0d9a21" class="m-doc-self">foo</a>(</span><span class="m-doc-wrap">)</span>
+            </dt>
+            <dd>A function with (detailed) include information but no details if includes are disabled.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/documentation/test_doxygen/compound_includes_undocumented_files/Doxyfile b/documentation/test_doxygen/compound_includes_undocumented_files/Doxyfile
index 9d4129f95cdc6129f7f0b4129d62dfd796706b0d..708d36f98263e87077a25118e83b3f9fbddca352 100644 (file)
--- 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 226242b2cbaf0f1d4bb39d4c97df8dca88b0d74c..bddea706a3176e039567e7eb5c009d5f809255d8 100644 (file)
--- 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<class T> 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 3d15b3f97da35c8dea91ead9316837ed6cc24455..72d7f0896a2722c16e3b73536da7df632174fe1b 100644 (file)
--- 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):