doxygen: JAVADOC_AUTOBRIEF is... wow. I need to take a shower.

Or, don't blow up on an unfortunate series of bad events.

1. If a file has a copyright header starting with /// and delimited with
   **** and JAVADOC_AUTOBRIEF is set to ON, Doxygen treats the first ***
   line as a brief documentation, which then made m.css fail because it
   doesn't expect stuff like <para><hruler/></para> inside
   <briefdescriptions>. The <hruler/> is still not implemented yet,
   though.

2. Who would have thought that

       /// A brief docs.
       /// @{
       /// Some detailed docs.

   would be understood as a two-paragraph brief?!

3. And who would have thought that

       /// ============
       /// The Thing
       /// ============

    would create a brief containing some === characters and a <heading>
    inside?! Here I just give up and ignore the whole thing.

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 6c0f03506537aac927e726b69bcaf5c566aa2eac..31e38a2de1ceeed03b7ec5e62335a1b3de96451f 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -1256,10 +1256,33 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
     # Brief description always needs to be single paragraph because we're
     # sending it out without enclosing <p>.
     if element.tag == 'briefdescription':
-        assert not has_block_elements and paragraph_count <= 1
-        if paragraph_count == 1:
-            assert out.parsed.startswith('<p>') and out.parsed.endswith('</p>')
-            out.parsed = out.parsed[3:-4]
+        # JAVADOC_AUTOBRIEF is *bad*
+        if state.doxyfile.get('JAVADOC_AUTOBRIEF', False):
+            # See the contents_brief_heading test for details
+            if has_block_elements:
+                logging.warning("{}: JAVADOC_AUTOBRIEF produced a brief description with block elements. That's not supported, ignoring the whole contents of {}".format(state.current, out.parsed))
+                out.parsed = ''
+
+            # See the contents_brief_multiline test for details
+            elif paragraph_count > 1:
+                logging.warning("{}: JAVADOC_AUTOBRIEF produced a multi-line brief description. That's not supported, using just the first paragraph of {}".format(state.current, out.parsed))
+
+                end = out.parsed.find('</p>')
+                assert out.parsed.startswith('<p>') and end != -1
+                out.parsed = out.parsed[3:end]
+
+            # See contents_brief_hr for why I need to check for out.parsed
+            elif paragraph_count == 1 and out.parsed:
+                assert out.parsed.startswith('<p>') and out.parsed.endswith('</p>')
+                out.parsed = out.parsed[3:-4]
+
+        # Sane behavior otherwise
+        else:
+            assert not has_block_elements and paragraph_count <= 1
+
+            if paragraph_count == 1:
+                assert out.parsed.startswith('<p>') and out.parsed.endswith('</p>')
+                out.parsed = out.parsed[3:-4]
 
     # Strip superfluous <p> for simple elments (list items, parameter and
     # return value description, table cells), but only if there is just a
@@ -2737,6 +2760,7 @@ list using <span class="m-label m-dim">&darr;</span> and
 
     # Boolean values that we want
     for i in ['CREATE_SUBDIRS',
+              'JAVADOC_AUTOBRIEF',
               'M_EXPAND_INNER_TYPES',
               'M_SEARCH_DISABLED',
               'M_SEARCH_DOWNLOAD_BINARY']:

diff --git a/doxygen/test/contents_autobrief_heading/Doxyfile b/doxygen/test/contents_autobrief_heading/Doxyfile
new file mode 100644 (file)
index 0000000..86eba78
--- /dev/null
+++ b/doxygen/test/contents_autobrief_heading/Doxyfile
@@ -0,0 +1,15 @@
+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_LINKS_NAVBAR1         =
+M_LINKS_NAVBAR2         =
+M_SEARCH_DISABLED       = YES
+
+# So the ==== is treated as brief. Ugh.
+JAVADOC_AUTOBRIEF       = YES

diff --git a/doxygen/test/contents_autobrief_heading/File.h b/doxygen/test/contents_autobrief_heading/File.h
new file mode 100644 (file)
index 0000000..274bc76
--- /dev/null
+++ b/doxygen/test/contents_autobrief_heading/File.h
@@ -0,0 +1,4 @@
+/// ===============
+/// The Thing
+/// ===============
+namespace Namespace {}

diff --git a/doxygen/test/contents_autobrief_heading/namespaceNamespace.html b/doxygen/test/contents_autobrief_heading/namespaceNamespace.html
new file mode 100644 (file)
index 0000000..0e27665
--- /dev/null
+++ b/doxygen/test/contents_autobrief_heading/namespaceNamespace.html
@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Namespace namespace | 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>Namespace <span class="m-thin">namespace</span></h1>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/doxygen/test/contents_autobrief_hr/Doxyfile b/doxygen/test/contents_autobrief_hr/Doxyfile
new file mode 100644 (file)
index 0000000..7d7365d
--- /dev/null
+++ b/doxygen/test/contents_autobrief_hr/Doxyfile
@@ -0,0 +1,15 @@
+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_LINKS_NAVBAR1         =
+M_LINKS_NAVBAR2         =
+M_SEARCH_DISABLED       = YES
+
+# So the comment on top is treated as a brief
+JAVADOC_AUTOBRIEF       = YES

diff --git a/doxygen/test/contents_autobrief_hr/File.h b/doxygen/test/contents_autobrief_hr/File.h
new file mode 100644 (file)
index 0000000..a6d3709
--- /dev/null
+++ b/doxygen/test/contents_autobrief_hr/File.h
@@ -0,0 +1,12 @@
+/// **************
+///
+/// SOME HEAVY LICENSE HEADER WITH SOME HEAVY WORDS
+///
+/// **************
+
+namespace Namespace {
+
+/// Some normal brief documentation
+void foo();
+
+}

diff --git a/doxygen/test/contents_autobrief_hr/namespaceNamespace.html b/doxygen/test/contents_autobrief_hr/namespaceNamespace.html
new file mode 100644 (file)
index 0000000..fa1eafe
--- /dev/null
+++ b/doxygen/test/contents_autobrief_hr/namespaceNamespace.html
@@ -0,0 +1,49 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Namespace namespace | 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>Namespace <span class="m-thin">namespace</span></h1>
+        <div class="m-block m-default">
+          <h3>Contents</h3>
+          <ul>
+            <li>
+              Reference
+              <ul>
+                <li><a href="#func-members">Functions</a></li>
+              </ul>
+            </li>
+          </ul>
+        </div>
+<p>SOME HEAVY LICENSE HEADER WITH SOME HEAVY WORDS</p>
+        <section id="func-members">
+          <h2><a href="#func-members">Functions</a></h2>
+          <dl class="m-dox">
+            <dt>
+              <span class="m-dox-wrap-bumper">void <a href="#a0f1fe1a972c7c4196988a1bdde63ec77" class="m-dox-self" name="a0f1fe1a972c7c4196988a1bdde63ec77">foo</a>(</span><span class="m-dox-wrap">)</span>
+            </dt>
+            <dd>Some normal brief documentation.</dd>
+          </dl>
+        </section>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/doxygen/test/contents_autobrief_multiline/Doxyfile b/doxygen/test/contents_autobrief_multiline/Doxyfile
new file mode 100644 (file)
index 0000000..14fcdeb
--- /dev/null
+++ b/doxygen/test/contents_autobrief_multiline/Doxyfile
@@ -0,0 +1,15 @@
+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_LINKS_NAVBAR1         =
+M_LINKS_NAVBAR2         =
+M_SEARCH_DISABLED       = YES
+
+# So the two lines on top are treated as brief. Wtf.
+JAVADOC_AUTOBRIEF       = YES

diff --git a/doxygen/test/contents_autobrief_multiline/File.h b/doxygen/test/contents_autobrief_multiline/File.h
new file mode 100644 (file)
index 0000000..e583734
--- /dev/null
+++ b/doxygen/test/contents_autobrief_multiline/File.h
@@ -0,0 +1,4 @@
+/// First line of a brief output
+/// @{
+/// Second line of a brief output gets ignored with a warning
+namespace Namespace {}

diff --git a/doxygen/test/contents_autobrief_multiline/namespaceNamespace.html b/doxygen/test/contents_autobrief_multiline/namespaceNamespace.html
new file mode 100644 (file)
index 0000000..d4e2d0c
--- /dev/null
+++ b/doxygen/test/contents_autobrief_multiline/namespaceNamespace.html
@@ -0,0 +1,29 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Namespace namespace | 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>Namespace <span class="m-thin">namespace</span></h1>
+        <p>First line of a brief output</p>
+      </div>
+    </div>
+  </div>
+</article></main>
+</body>
+</html>

diff --git a/doxygen/test/test_contents.py b/doxygen/test/test_contents.py
index 6473ee8dc32270632c9699a7646598b0b66a53b0..9c0387deebed125f9548cf02c1b04c1d3cf9fad5 100644 (file)
--- a/doxygen/test/test_contents.py
+++ b/doxygen/test/test_contents.py
@@ -142,3 +142,30 @@ class ParseError(BaseTestCase):
 
         # The index file should be generated, no abort
         self.assertTrue(os.path.exists(os.path.join(self.path, 'html', 'index.html')))
+
+# JAVADOC_AUTOBRIEF should be nuked from orbit. Or implemented from scratch,
+# properly.
+
+class AutobriefHr(IntegrationTestCase):
+    def __init__(self, *args, **kwargs):
+        super().__init__(__file__, 'autobrief_hr', *args, **kwargs)
+
+    def test(self):
+        self.run_dox2html5(wildcard='namespaceNamespace.xml')
+        self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html'))
+
+class AutobriefMultiline(IntegrationTestCase):
+    def __init__(self, *args, **kwargs):
+        super().__init__(__file__, 'autobrief_multiline', *args, **kwargs)
+
+    def test(self):
+        self.run_dox2html5(wildcard='namespaceNamespace.xml')
+        self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html'))
+
+class AutobriefHeading(IntegrationTestCase):
+    def __init__(self, *args, **kwargs):
+        super().__init__(__file__, 'autobrief_heading', *args, **kwargs)
+
+    def test(self):
+        self.run_dox2html5(wildcard='namespaceNamespace.xml')
+        self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html'))