From: Vladimír Vondruš Date: Mon, 10 Jan 2022 11:39:14 +0000 (+0100) Subject: Revert "documentation/doxygen: drop handling for a Doxygen 1.8.15 bug." X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=92b6a005d3c6a3599c995c0be4c268404cecacc7;p=blog.git Revert "documentation/doxygen: drop handling for a Doxygen 1.8.15 bug." Turns out it's not really A Thing Of The Past yet -- the assertion is firing for different cases and the message of it is utterly confusing. Repro case for the others in the following commit. This reverts commit 6bea7027cb2674e4c5f78a527ddab506d9785675. --- diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 824e6413..dee5b522 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -1688,13 +1688,20 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. assert out.parsed.startswith('

') and out.parsed.endswith('

') out.parsed = out.parsed[3:-4] - # Sane behavior otherwise + # Sane behavior otherwise. Well, no. I give up. else: - assert not has_block_elements and paragraph_count <= 1, \ - "{}: brief description containing multiple paragraphs, possibly due to @ingroup following a @brief in {}. This was a bug in Doxygen 1.8.15/16 and fixed since, please upgrade.".format(state.current, out.parsed) - if paragraph_count == 1: - assert out.parsed.startswith('

') and out.parsed.endswith('

') - out.parsed = out.parsed[3:-4] + # In 1.8.15 if @brief is followed by an @ingroup, then the + # immediately following paragraph gets merged with it for some + # freaking reason. See the contents_brief_multiline_ingroup test + # for details. Fixed since 1.8.16. + if paragraph_count > 1: + logging.warning("{}: brief description containing multiple paragraphs, possibly due to @ingroup following a @brief. That's not supported, ignoring the whole contents of {}".format(state.current, out.parsed)) + out.parsed = '' + 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 diff --git a/documentation/test_doxygen/contents_brief_multiline_ingroup/Doxyfile b/documentation/test_doxygen/contents_brief_multiline_ingroup/Doxyfile new file mode 100644 index 00000000..7e9ad922 --- /dev/null +++ b/documentation/test_doxygen/contents_brief_multiline_ingroup/Doxyfile @@ -0,0 +1,14 @@ +INPUT = File.h +QUIET = YES +GENERATE_HTML = NO +GENERATE_LATEX = NO +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 diff --git a/documentation/test_doxygen/contents_brief_multiline_ingroup/File.h b/documentation/test_doxygen/contents_brief_multiline_ingroup/File.h new file mode 100644 index 00000000..deb92f4b --- /dev/null +++ b/documentation/test_doxygen/contents_brief_multiline_ingroup/File.h @@ -0,0 +1,10 @@ +/** @defgroup thatgroup This is a group */ + +/** +@brief Function that's in a group +@ingroup thatgroup + +Lines of detailed description that get merged to the brief for no freaking +reason. +*/ +void foo(); diff --git a/documentation/test_doxygen/contents_brief_multiline_ingroup/group__thatgroup.html b/documentation/test_doxygen/contents_brief_multiline_ingroup/group__thatgroup.html new file mode 100644 index 00000000..cf0a91e1 --- /dev/null +++ b/documentation/test_doxygen/contents_brief_multiline_ingroup/group__thatgroup.html @@ -0,0 +1,59 @@ + + + + + This is a group module | My Project + + + + + +

+ This is a group module

+ +

Functions

+ void foo() +: Function that's in a group.

Function documentation

+ void foo() +

Function that's in a group.

Lines of detailed description that get merged to the brief for no freaking reason.

+ + diff --git a/documentation/test_doxygen/contents_brief_multiline_ingroup/group__thatgroup_1815.html b/documentation/test_doxygen/contents_brief_multiline_ingroup/group__thatgroup_1815.html new file mode 100644 index 00000000..13e9cf2a --- /dev/null +++ b/documentation/test_doxygen/contents_brief_multiline_ingroup/group__thatgroup_1815.html @@ -0,0 +1,29 @@ + + + + + This is a group module | My Project + + + + + +

+ This is a group module

+ + diff --git a/documentation/test_doxygen/test_contents.py b/documentation/test_doxygen/test_contents.py index 58467601..0f851636 100644 --- a/documentation/test_doxygen/test_contents.py +++ b/documentation/test_doxygen/test_contents.py @@ -357,6 +357,26 @@ class AutobriefHeading(IntegrationTestCase): self.run_doxygen(wildcard='namespaceNamespace.xml') self.assertEqual(*self.actual_expected_contents('namespaceNamespace.html')) +class BriefMultilineIngroup(IntegrationTestCase): + @unittest.skipUnless(LooseVersion(doxygen_version()) < LooseVersion("1.8.16"), + "1.8.16 doesn't merge adjacent paragraphs into brief in presence of an @ingroup anymore") + def test_1815(self): + with self.assertLogs() as cm: + self.run_doxygen(wildcard='group__thatgroup.xml') + + self.assertEqual(*self.actual_expected_contents('group__thatgroup.html', 'group__thatgroup_1815.html')) + self.assertEqual(cm.output, [ + "WARNING:root:group__thatgroup.xml: brief description containing multiple paragraphs, possibly due to @ingroup following a @brief. That's not supported, ignoring the whole contents of

Function that's in a group

Lines of detailed description that get merged to the brief for no freaking reason.

" + ]) + + @unittest.skipUnless(LooseVersion(doxygen_version()) >= LooseVersion("1.8.16"), + "1.8.16 doesn't merge adjacent paragraphs into brief in presence of an @ingroup anymore") + def test(self): + # No warnings should be produced here + # TODO use self.assertNoLongs() on 3.10+ + self.run_doxygen(wildcard='group__thatgroup.xml') + self.assertEqual(*self.actual_expected_contents('group__thatgroup.html')) + class SectionUnderscoreOne(IntegrationTestCase): def test(self): self.run_doxygen(wildcard='indexpage.xml')