File.h file | My Project

From 1f969feffef7b76bda5ec30d35c5e8a1f0a23982 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Mon, 10 Jan 2022 13:02:47 +0100 Subject: [PATCH] documentation/doxygen: repro case & fix for a blockquote in brief. Amazing. Such a *tiny* piece of functionality with a clear goal, providing a single-line brief with no block elements. And yet this is like the 50th bug I came across, so far. --- documentation/doxygen.py | 17 +++--- .../contents_autobrief_blockquote/Doxyfile | 17 ++++++ .../contents_autobrief_blockquote/File.h | 10 ++++ .../File_8h.html | 59 +++++++++++++++++++ documentation/test_doxygen/test_contents.py | 12 +++- 5 files changed, 107 insertions(+), 8 deletions(-) create mode 100644 documentation/test_doxygen/contents_autobrief_blockquote/Doxyfile create mode 100644 documentation/test_doxygen/contents_autobrief_blockquote/File.h create mode 100644 documentation/test_doxygen/contents_autobrief_blockquote/File_8h.html diff --git a/documentation/doxygen.py b/documentation/doxygen.py index dee5b522..e4d9c931 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -1694,14 +1694,17 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. # 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)) + # + # In 1.8.18+, if ///> is accidentally used to mark "a docblock for + # the following symbol", it leads to a

contained in + # the brief. Not much to do except for ignoring the whole thing. + # See the contents_autobrief_blockquote test for details. + if has_block_elements or paragraph_count > 1: + logging.warning("{}: ignoring brief description containing multiple paragraphs. Please modify your markup to remove any block elements from the following: {}".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] + elif 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_autobrief_blockquote/Doxyfile b/documentation/test_doxygen/contents_autobrief_blockquote/Doxyfile new file mode 100644 index 00000000..bf3f5a30 --- /dev/null +++ b/documentation/test_doxygen/contents_autobrief_blockquote/Doxyfile @@ -0,0 +1,17 @@ +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 + +# In this case neither JAVADOC_AUTOBRIEF nor QT_AUTOBRIEF needs to be set to +# recognize the first line of /// comments as brief diff --git a/documentation/test_doxygen/contents_autobrief_blockquote/File.h b/documentation/test_doxygen/contents_autobrief_blockquote/File.h new file mode 100644 index 00000000..ab5607e7 --- /dev/null +++ b/documentation/test_doxygen/contents_autobrief_blockquote/File.h @@ -0,0 +1,10 @@ +/// @file +/// A file + +///> An enum on the right +enum Enum { + Value ///< A value on the right +}; + +/* ... where > actually isn't interpreted as "documentation for what follows" + but rather a Markdown blockquote */ diff --git a/documentation/test_doxygen/contents_autobrief_blockquote/File_8h.html b/documentation/test_doxygen/contents_autobrief_blockquote/File_8h.html new file mode 100644 index 00000000..65d2e34e --- /dev/null +++ b/documentation/test_doxygen/contents_autobrief_blockquote/File_8h.html @@ -0,0 +1,59 @@ + + + + + File.h file | My Project + + + + + +
+
+
+ My Project +
+
+
+
+
+
+
+
+ File.h file +
+
A file
+
+
Enums
+
+
+ enum Enum { Value } +
+
+
+
+
+
Enum documentation
+
+
+ enum Enum +
+ + + + + + + + +
Enumerators
Value +
A value on the right.
+
+
+
+
+
+
+
+ + diff --git a/documentation/test_doxygen/test_contents.py b/documentation/test_doxygen/test_contents.py index 0f851636..a505c867 100644 --- a/documentation/test_doxygen/test_contents.py +++ b/documentation/test_doxygen/test_contents.py @@ -296,6 +296,16 @@ class AutobriefCppComments(IntegrationTestCase): self.run_doxygen(wildcard='File_8h.xml') self.assertEqual(*self.actual_expected_contents('File_8h.html')) +class AutobriefBlockquote(IntegrationTestCase): + def test(self): + with self.assertLogs() as cm: + self.run_doxygen(wildcard='File_8h.xml') + + self.assertEqual(*self.actual_expected_contents('File_8h.html')) + self.assertEqual(cm.output, [ + "WARNING:root:File_8h.xml: ignoring brief description containing multiple paragraphs. Please modify your markup to remove any block elements from the following:
An enum on the right
" + ]) + # JAVADOC_AUTOBRIEF should be nuked from orbit. Or implemented from scratch, # properly. @@ -366,7 +376,7 @@ class BriefMultilineIngroup(IntegrationTestCase): 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.
" + "WARNING:root:group__thatgroup.xml: ignoring brief description containing multiple paragraphs. Please modify your markup to remove any block elements from the following:
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"), -- 2.30.2