File.h file | My Project

From cc8c5c6ef7585d6a627d1877dafae532819c414d Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Sat, 14 Sep 2024 00:52:29 +0200 Subject: [PATCH] documentation/doxygen: some Markdown autobrief insanities gone in 1.12. --- documentation/doxygen.py | 5 +- .../File_8h-111.html | 59 +++++++++++++++++++ .../File_8h.html | 1 + documentation/test_doxygen/test_contents.py | 20 +++++-- 4 files changed, 79 insertions(+), 6 deletions(-) create mode 100644 documentation/test_doxygen/contents_autobrief_blockquote/File_8h-111.html diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 3faf179f..c56ae60b 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -1781,7 +1781,10 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. # 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. + # See the contents_autobrief_blockquote test for details. Doesn't + # happen in 1.12 anymore, not sure if that changed due to + # https://github.com/doxygen/doxygen/issues/10902 or something + # else in some earlier version. 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 = '' diff --git a/documentation/test_doxygen/contents_autobrief_blockquote/File_8h-111.html b/documentation/test_doxygen/contents_autobrief_blockquote/File_8h-111.html new file mode 100644 index 00000000..65d2e34e --- /dev/null +++ b/documentation/test_doxygen/contents_autobrief_blockquote/File_8h-111.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/contents_autobrief_blockquote/File_8h.html b/documentation/test_doxygen/contents_autobrief_blockquote/File_8h.html index 65d2e34e..2e769c0a 100644 --- a/documentation/test_doxygen/contents_autobrief_blockquote/File_8h.html +++ b/documentation/test_doxygen/contents_autobrief_blockquote/File_8h.html @@ -38,6 +38,7 @@
enum Enum
+
An enum on the right
diff --git a/documentation/test_doxygen/test_contents.py b/documentation/test_doxygen/test_contents.py index 5c42767a..3bc42a93 100644 --- a/documentation/test_doxygen/test_contents.py +++ b/documentation/test_doxygen/test_contents.py @@ -300,13 +300,23 @@ class AutobriefCppComments(IntegrationTestCase): class AutobriefBlockquote(IntegrationTestCase): def test(self): - with self.assertLogs() as cm: + # ///> in a brief used to cause a multi-line brief in 1.8.18+, which + # caused the whole brief to be discarded with a warning. That's no + # longer the case in 1.12, there it's put into the detailed description + # instead. Not sure if that changed due to + # https://github.com/doxygen/doxygen/issues/10902 or something else in + # some earlier version. + if parse_version(doxygen_version()) >= (1, 12): self.run_doxygen(wildcard='File_8h.xml') + self.assertEqual(*self.actual_expected_contents('File_8h.html')) + else: + 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
" - ]) + self.assertEqual(*self.actual_expected_contents('File_8h.html', 'File_8h-111.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. -- 2.30.2

Enumerators