From: Vladimír Vondruš Date: Wed, 25 Apr 2018 11:40:23 +0000 (+0200) Subject: doxygen: JAVADOC_AUTOBRIEF is... wow. I need to take a shower. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=406ecd7427081b62dc6787f2611eeee48ca4f500;p=blog.git 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 inside . The 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 inside?! Here I just give up and ignore the whole thing. --- diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 6c0f0350..31e38a2d 100755 --- 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

. if element.tag == 'briefdescription': - assert not has_block_elements and paragraph_count <= 1 - if paragraph_count == 1: - assert out.parsed.startswith('

') and out.parsed.endswith('

') - 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('

') + assert out.parsed.startswith('

') 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('

') and out.parsed.endswith('

') + 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('

') and out.parsed.endswith('

') + out.parsed = out.parsed[3:-4] # Strip superfluous

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 ↓ 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 index 00000000..86eba784 --- /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 index 00000000..274bc76d --- /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 index 00000000..0e276659 --- /dev/null +++ b/doxygen/test/contents_autobrief_heading/namespaceNamespace.html @@ -0,0 +1,28 @@ + + + + + Namespace namespace | My Project + + + + + +

+
+
+
+
+

Namespace namespace

+
+
+
+
+ + diff --git a/doxygen/test/contents_autobrief_hr/Doxyfile b/doxygen/test/contents_autobrief_hr/Doxyfile new file mode 100644 index 00000000..7d7365d5 --- /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 index 00000000..a6d3709d --- /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 index 00000000..fa1eafe3 --- /dev/null +++ b/doxygen/test/contents_autobrief_hr/namespaceNamespace.html @@ -0,0 +1,49 @@ + + + + + Namespace namespace | My Project + + + + + +
+
+
+
+
+

Namespace namespace

+
+

Contents

+ +
+

SOME HEAVY LICENSE HEADER WITH SOME HEAVY WORDS

+
+

Functions

+
+
+ void foo() +
+
Some normal brief documentation.
+
+
+
+
+
+
+ + diff --git a/doxygen/test/contents_autobrief_multiline/Doxyfile b/doxygen/test/contents_autobrief_multiline/Doxyfile new file mode 100644 index 00000000..14fcdeba --- /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 index 00000000..e583734c --- /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 index 00000000..d4e2d0ce --- /dev/null +++ b/doxygen/test/contents_autobrief_multiline/namespaceNamespace.html @@ -0,0 +1,29 @@ + + + + + Namespace namespace | My Project + + + + + +
+
+
+
+
+

Namespace namespace

+

First line of a brief output

+
+
+
+
+ + diff --git a/doxygen/test/test_contents.py b/doxygen/test/test_contents.py index 6473ee8d..9c0387de 100644 --- 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'))