doxygen: don't assert on unexpected sections / commands.

Until now, putting a @param into a variable description (or similar
unexpected things) resulted in an assertion. Turns out this happens
quite often, so I made that into a warning instead. The contents are
simply ignored.

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index d79b8e369db35581f855105f5229abceb1d6f854..4e092e8d86cee990268d6d72f1f62123e2cd12ed 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -1387,25 +1387,25 @@ def parse_desc_keywords(state: State, element: ET.Element) -> str:
     return parsed.parsed, parsed.search_keywords, parsed.search_enum_values_as_keywords
 
 def parse_enum_desc(state: State, element: ET.Element) -> str:
-    # Verify that we didn't ignore any important info by accident
     parsed = parse_desc_internal(state, element.find('detaileddescription'))
     parsed.parsed += parse_desc(state, element.find('inbodydescription'))
-    assert not parsed.templates and not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions
+    if parsed.templates or parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions:
+        logging.warning("{}: unexpected @tparam / @param / @return / @retval / @exception found in enum description, ignoring".format(state.current))
     assert not parsed.section # might be problematic
     return (parsed.parsed, parsed.search_keywords, parsed.search_enum_values_as_keywords, parsed.is_deprecated)
 
 def parse_enum_value_desc(state: State, element: ET.Element) -> str:
-    # Verify that we didn't ignore any important info by accident
     parsed = parse_desc_internal(state, element.find('detaileddescription'))
-    assert not parsed.templates and not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions
+    if parsed.templates or parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions:
+        logging.warning("{}: unexpected @tparam / @param / @return / @retval / @exception found in enum value description, ignoring".format(state.current))
     assert not parsed.section # might be problematic
     return (parsed.parsed, parsed.search_keywords, parsed.is_deprecated)
 
 def parse_var_desc(state: State, element: ET.Element) -> str:
-    # Verify that we didn't ignore any important info by accident
     parsed = parse_desc_internal(state, element.find('detaileddescription'))
     parsed.parsed += parse_desc(state, element.find('inbodydescription'))
-    assert not parsed.templates and not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions
+    if parsed.templates or parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions:
+        logging.warning("{}: unexpected @tparam / @param / @return / @retval / @exception found in variable description, ignoring".format(state.current))
     assert not parsed.section # might be problematic
     return (parsed.parsed, parsed.search_keywords, parsed.is_deprecated)
 
@@ -1413,33 +1413,29 @@ def parse_toplevel_desc(state: State, element: ET.Element):
     state.parsing_toplevel_desc = True
     parsed = parse_desc_internal(state, element)
     state.parsing_toplevel_desc = False
-    # Verify that we didn't ignore any important info by accident
-    assert not parsed.return_value and not parsed.return_values and not parsed.exceptions
-    if parsed.params:
-        logging.warning("{}: use @tparam instead of @param for documenting class templates, @param is ignored".format(state.current))
+    if parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions:
+        logging.warning("{}: unexpected @param / @return / @retval / @exception found in top-level description, ignoring".format(state.current))
     return (parsed.parsed, parsed.templates, parsed.section[2] if parsed.section else '', parsed.footer_navigation, parsed.example_navigation, parsed.search_keywords, parsed.is_deprecated)
 
 def parse_typedef_desc(state: State, element: ET.Element):
-    # Verify that we didn't ignore any important info by accident
     parsed = parse_desc_internal(state, element.find('detaileddescription'))
     parsed.parsed += parse_desc(state, element.find('inbodydescription'))
-    assert not parsed.params and not parsed.return_value and not parsed.return_values and not parsed.exceptions
+    if parsed.params or parsed.return_value or parsed.return_values or parsed.exceptions:
+        logging.warning("{}: unexpected @param / @return / @retval / @exception found in typedef description, ignoring".format(state.current))
     assert not parsed.section # might be problematic
     return (parsed.parsed, parsed.templates, parsed.search_keywords, parsed.is_deprecated)
 
 def parse_func_desc(state: State, element: ET.Element):
-    # Verify that we didn't ignore any important info by accident
     parsed = parse_desc_internal(state, element.find('detaileddescription'))
     parsed.parsed += parse_desc(state, element.find('inbodydescription'))
     assert not parsed.section # might be problematic
     return (parsed.parsed, parsed.templates, parsed.params, parsed.return_value, parsed.return_values, parsed.exceptions, parsed.search_keywords, parsed.is_deprecated)
 
 def parse_define_desc(state: State, element: ET.Element):
-    # Verify that we didn't ignore any important info by accident
     parsed = parse_desc_internal(state, element.find('detaileddescription'))
     parsed.parsed += parse_desc(state, element.find('inbodydescription'))
-    assert not parsed.templates and not parsed.exceptions
-    assert not parsed.return_values # might be problematic?
+    if parsed.templates or parsed.return_values or parsed.exceptions:
+        logging.warning("{}: unexpected @tparam / @retval / @exception found in macro description, ignoring".format(state.current))
     assert not parsed.section # might be problematic
     return (parsed.parsed, parsed.params, parsed.return_value, parsed.search_keywords, parsed.is_deprecated)
 

diff --git a/doxygen/test/contents_unexpected_sections/Doxyfile b/doxygen/test/contents_unexpected_sections/Doxyfile
new file mode 100644 (file)
index 0000000..49e476e
--- /dev/null
+++ b/doxygen/test/contents_unexpected_sections/Doxyfile
@@ -0,0 +1,13 @@
+INPUT                   = File.h
+QUIET                   = YES
+GENERATE_HTML           = NO
+GENERATE_LATEX          = NO
+GENERATE_XML            = YES
+XML_PROGRAMLISTING      = NO
+
+##! M_PAGE_FINE_PRINT   =
+##! M_THEME_COLOR       =
+##! M_FAVICON           =
+##! M_LINKS_NAVBAR1     =
+##! M_LINKS_NAVBAR2     =
+##! M_SEARCH_DISABLED   = YES

diff --git a/doxygen/test/contents_unexpected_sections/File.h b/doxygen/test/contents_unexpected_sections/File.h
new file mode 100644 (file)
index 0000000..c941b65
--- /dev/null
+++ b/doxygen/test/contents_unexpected_sections/File.h
@@ -0,0 +1,34 @@
+/** @file
+@brief A file
+
+@return Files don't return anyhting.
+*/
+
+/**
+@brief An enum
+@param what No, enums don't have params.
+*/
+enum Foo {
+    /**
+     * @return Neither this.
+     */
+    Value = 32
+};
+
+/**
+@brief A variable
+@exception no Variables don't throw exceptions.
+*/
+int variable;
+
+/**
+@brief A typedef
+@return Typedefs don't have return values.
+*/
+typedef Foo Bar;
+
+/**
+@brief A define
+@tparam T Defines don't have templates.
+*/
+#define FOOBAR 3

diff --git a/doxygen/test/contents_unexpected_sections/File_8h.html b/doxygen/test/contents_unexpected_sections/File_8h.html
new file mode 100644 (file)
index 0000000..4c21646
--- /dev/null
+++ b/doxygen/test/contents_unexpected_sections/File_8h.html
@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>File.h file | 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+doxygen.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>
+          File.h <span class="m-thin">file</span>
+        </h1>
+        <p>A file.</p>
+        <div class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#enum-members">Enums</a></li>
+                <li><a href="#typedef-members">Typedefs</a></li>
+                <li><a href="#var-members">Variables</a></li>
+                <li><a href="#defines">Defines</a></li>
+              </ul>
+            </li>
+          </ul>
+        </div>
+        <section id="enum-members">
+          <h2><a href="#enum-members">Enums</a></h2>
+          <dl class="m-dox">
+            <dt>
+              <span class="m-dox-wrap-bumper">enum <a href="#aa621f6f849ec2327dabfc4392fd59a70" class="m-dox-self" name="aa621f6f849ec2327dabfc4392fd59a70">Foo</a> { </span><span class="m-dox-wrap"><a href="#aa621f6f849ec2327dabfc4392fd59a70a050889cfb2c606473596b8f70f702769" class="m-dox">Value</a> = 32 }</span>
+            </dt>
+            <dd>An enum.</dd>
+          </dl>
+        </section>
+        <section id="typedef-members">
+          <h2><a href="#typedef-members">Typedefs</a></h2>
+          <dl class="m-dox">
+            <dt>
+              using <a href="#ab3c402cbc128c888732541f75dbd3952" class="m-dox-self" name="ab3c402cbc128c888732541f75dbd3952">Bar</a> = <a href="File_8h.html#aa621f6f849ec2327dabfc4392fd59a70" class="m-dox">Foo</a>
+            </dt>
+            <dd>A typedef.</dd>
+          </dl>
+        </section>
+        <section id="var-members">
+          <h2><a href="#var-members">Variables</a></h2>
+          <dl class="m-dox">
+            <dt>int <a href="#ac2bb0fc1fabbeabad94c3b726bd708bc" class="m-dox-self" name="ac2bb0fc1fabbeabad94c3b726bd708bc">variable</a></dt>
+            <dd>A variable.</dd>
+          </dl>
+        </section>
+        <section id="define-members">
+          <h2><a href="#define-members">Defines</a></h2>
+          <dl class="m-dox">
+            <dt>
+              <span class="m-dox-wrap-bumper">#define <a href="#afac708c45da370b4c1304f4b69f7fc75" class="m-dox-self" name="afac708c45da370b4c1304f4b69f7fc75">FOOBAR</a></span>
+            </dt>
+            <dd>A define.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/doxygen/test/test_contents.py b/doxygen/test/test_contents.py
index 721db559876fd612ae690ab88e136fdfed0e2e98..6b93c0b220761428511142961e174786410322ed 100644 (file)
--- a/doxygen/test/test_contents.py
+++ b/doxygen/test/test_contents.py
@@ -320,3 +320,11 @@ class AnchorInBothGroupAndNamespace(IntegrationTestCase):
     def test(self):
         self.run_dox2html5(wildcard='namespaceFoo.xml')
         self.assertEqual(*self.actual_expected_contents('namespaceFoo.html'))
+
+class UnexpectedSections(IntegrationTestCase):
+    def __init__(self, *args, **kwargs):
+        super().__init__(__file__, 'unexpected_sections', *args, **kwargs)
+
+    def test(self):
+        self.run_dox2html5(wildcard='File_8h.xml')
+        self.assertEqual(*self.actual_expected_contents('File_8h.html'))