doxygen: be compatible with stock HTML output for undocumented symbols.

In particular, if given compound has neither brief nor detailed docs,
produce output for it only if it's a page or a group (because those need
to be explicitly created). Before only file/dir docs behaved like this,
not namespaces or classes.

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 609df177f2f077aec85cfcd3ccdb47b675d6ada4..882c94f7a772b34c87e25864ef521c40170cb742 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -1633,9 +1633,9 @@ def extract_metadata(state: State, xml):
     # Compound URL is ID, except for index page
     compound.url = (compounddef.find('compoundname').text if compound.kind == 'page' else compound.id) + '.html'
     compound.brief = parse_desc(state, compounddef.find('briefdescription'))
-    # Groups are explicitly created so they *have details*, other things need
-    # to have at least some documentation
-    compound.has_details = compound.kind == 'group' or compound.brief or compounddef.find('detaileddescription')
+    # Groups and pages are explicitly created so they *have details*, other
+    # things need to have at least some documentation
+    compound.has_details = compound.kind in ['group', 'page'] or compound.brief or compounddef.find('detaileddescription')
     compound.children = []
     compound.parent = None # is filled in by postprocess_state()
 
@@ -1856,9 +1856,10 @@ def parse_xml(state: State, xml: str):
         logging.debug("{}: only private things, skipping".format(state.current))
         return None
 
-    # Ignoring dirs/files w/o any description
-    if compounddef.attrib['kind'] in ['dir', 'file'] and not compounddef.find('briefdescription') and not compounddef.find('detaileddescription'):
-        logging.debug("{}: file/dir documentation empty, skipping".format(state.current))
+    # Ignoring compounds w/o any description, except for pages and groups,
+    # which are created explicitly
+    if not compounddef.find('briefdescription') and not compounddef.find('detaileddescription') and not compounddef.attrib['kind'] in ['page', 'group']:
+        logging.debug("{}: neither brief nor detailed description present, skipping".format(state.current))
         return None
 
     compound = Empty()

diff --git a/doxygen/test/compound_detailed/File.h b/doxygen/test/compound_detailed/File.h
index 3d6329c662c1d54f776fa1425796c374139bf10f..401cd8d2afd7d39b14f82fccb617b03f2c039ce3 100644 (file)
--- a/doxygen/test/compound_detailed/File.h
+++ b/doxygen/test/compound_detailed/File.h
@@ -91,6 +91,7 @@ And we have some detailed docs as well.
 */
 namespace Namee {}
 
+/** @brief A namespace */
 namespace Foo {
 
 /**
@@ -161,6 +162,7 @@ void thisIsAShittyWayToPassAVectorButWhatever(float x, float y, float z);
 
 }
 
+/** @brief A namespace */
 namespace Eno {
 
 /** @brief Boolean */
@@ -177,6 +179,7 @@ enum {
 
 }
 
+/** @brief A namespace */
 namespace Type {
 
 /**
@@ -195,6 +198,7 @@ typedef void(*Func)(int, std::string&);
 
 }
 
+/** @brief A namespace */
 namespace Var {
 
 /**
@@ -206,6 +210,7 @@ constexpr const int a = 25;
 
 }
 
+/** @brief A namespace */
 namespace Warning {
 
 /** @brief Use the brief! */

diff --git a/doxygen/test/compound_detailed/File_8h.html b/doxygen/test/compound_detailed/File_8h.html
index 450982846541542fadfe40c454de479a46887a61..3928cd1829fc530aa0df8f54bdff6e53dc371983 100644 (file)
--- a/doxygen/test/compound_detailed/File_8h.html
+++ b/doxygen/test/compound_detailed/File_8h.html
@@ -41,6 +41,16 @@
           <dl class="m-dox">
             <dt>namespace <a href="namespaceNamee.html" class="m-dox">Namee</a></dt>
             <dd>Namespace docs.</dd>
+            <dt>namespace <a href="namespaceFoo.html" class="m-dox">Foo</a></dt>
+            <dd>A namespace.</dd>
+            <dt>namespace <a href="namespaceEno.html" class="m-dox">Eno</a></dt>
+            <dd>A namespace.</dd>
+            <dt>namespace <a href="namespaceType.html" class="m-dox">Type</a></dt>
+            <dd>A namespace.</dd>
+            <dt>namespace <a href="namespaceVar.html" class="m-dox">Var</a></dt>
+            <dd>A namespace.</dd>
+            <dt>namespace <a href="namespaceWarning.html" class="m-dox">Warning</a></dt>
+            <dd>A namespace.</dd>
           </dl>
         </section>
         <section id="nested-classes">

diff --git a/doxygen/test/compound_detailed/namespaceEno.html b/doxygen/test/compound_detailed/namespaceEno.html
index 981ed8eaf8853162b42eb78f272900017e4a84d6..28ac577535418590559b2d9814f7b6fde3014aef 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceEno.html
+++ b/doxygen/test/compound_detailed/namespaceEno.html
@@ -20,6 +20,7 @@
     <div class="m-row">
       <div class="m-col-l-10 m-push-l-1">
         <h1>Eno <span class="m-thin">namespace</span></h1>
+        <p>A namespace.</p>
         <section id="enum-members">
           <h2><a href="#enum-members">Enums</a></h3>
           <dl class="m-dox">

diff --git a/doxygen/test/compound_detailed/namespaceFoo.html b/doxygen/test/compound_detailed/namespaceFoo.html
index 918fdfc2017d16fec4b1f4c84b28929e0a58597c..ec53c234e6ea50658f38d07ffcb99c83786fcce4 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceFoo.html
+++ b/doxygen/test/compound_detailed/namespaceFoo.html
@@ -20,6 +20,7 @@
     <div class="m-row">
       <div class="m-col-l-10 m-push-l-1">
         <h1>Foo <span class="m-thin">namespace</span></h1>
+        <p>A namespace.</p>
         <div class="m-block m-default">
           <h3>Contents</h3>
           <ul>

diff --git a/doxygen/test/compound_detailed/namespaceType.html b/doxygen/test/compound_detailed/namespaceType.html
index 458db06c3179e8e6d108c32aadace00e5fabf4a8..e5ac4c266fee32cf9004322a015ead88f1704a95 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceType.html
+++ b/doxygen/test/compound_detailed/namespaceType.html
@@ -20,6 +20,7 @@
     <div class="m-row">
       <div class="m-col-l-10 m-push-l-1">
         <h1>Type <span class="m-thin">namespace</span></h1>
+        <p>A namespace.</p>
         <div class="m-block m-default">
           <h3>Contents</h3>
           <ul>

diff --git a/doxygen/test/compound_detailed/namespaceVar.html b/doxygen/test/compound_detailed/namespaceVar.html
index 1a838d9e1981feaa78899b0af0c79a78a1be3dbf..4d841c40aa1f9b50831ff664e948e3091129ac98 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceVar.html
+++ b/doxygen/test/compound_detailed/namespaceVar.html
@@ -20,6 +20,7 @@
     <div class="m-row">
       <div class="m-col-l-10 m-push-l-1">
         <h1>Var <span class="m-thin">namespace</span></h1>
+        <p>A namespace.</p>
         <div class="m-block m-default">
           <h3>Contents</h3>
           <ul>

diff --git a/doxygen/test/compound_detailed/namespaceWarning.html b/doxygen/test/compound_detailed/namespaceWarning.html
index 5252e48b234bcbae21a5ff02531b260b2a95c1b7..dec9a10a75b3e48ba02d4e866217c4bcf44ed65e 100644 (file)
--- a/doxygen/test/compound_detailed/namespaceWarning.html
+++ b/doxygen/test/compound_detailed/namespaceWarning.html
@@ -20,6 +20,7 @@
     <div class="m-row">
       <div class="m-col-l-10 m-push-l-1">
         <h1>Warning <span class="m-thin">namespace</span></h1>
+        <p>A namespace.</p>
         <div class="m-block m-default">
           <h3>Contents</h3>
           <ul>