# 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 <blockquote> 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('<p>') and out.parsed.endswith('</p>')
- out.parsed = out.parsed[3:-4]
+ elif 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
--- /dev/null
+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
--- /dev/null
+/// @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 */
--- /dev/null
+<!DOCTYPE html>
+<html lang="en">
+<head>
+ <meta charset="UTF-8" />
+ <title>File.h file | 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+documentation.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>
+ File.h <span class="m-thin">file</span>
+ </h1>
+<p>A file</p>
+ <section id="enum-members">
+ <h2><a href="#enum-members">Enums</a></h2>
+ <dl class="m-doc">
+ <dt>
+ <span class="m-doc-wrap-bumper">enum <a href="#a8150b7776c2a1749101acf22e868d091" class="m-doc">Enum</a> { </span><span class="m-doc-wrap"><a href="#a8150b7776c2a1749101acf22e868d091a050889cfb2c606473596b8f70f702769" class="m-doc">Value</a> }</span>
+ </dt>
+ <dd></dd>
+ </dl>
+ </section>
+ <section>
+ <h2>Enum documentation</h2>
+ <section class="m-doc-details" id="a8150b7776c2a1749101acf22e868d091"><div>
+ <h3>
+ enum <a href="#a8150b7776c2a1749101acf22e868d091" class="m-doc-self">Enum</a>
+ </h3>
+ <table class="m-table m-fullwidth m-flat m-doc">
+ <thead><tr><th style="width: 1%">Enumerators</th><th></th></tr></thead>
+ <tbody>
+ <tr>
+ <td><a href="#a8150b7776c2a1749101acf22e868d091a050889cfb2c606473596b8f70f702769" class="m-doc-self" id="a8150b7776c2a1749101acf22e868d091a050889cfb2c606473596b8f70f702769">Value</a></td>
+ <td>
+ <p>A value on the right.</p>
+ </td>
+ </tr>
+ </tbody>
+ </table>
+ </div></section>
+ </section>
+ </div>
+ </div>
+ </div>
+</article></main>
+</body>
+</html>
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: <blockquote><p>An enum on the right</p></blockquote>"
+ ])
+
# JAVADOC_AUTOBRIEF should be nuked from orbit. Or implemented from scratch,
# properly.
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 <p>Function that's in a group</p><p>Lines of detailed description that get merged to the brief for no freaking reason.</p>"
+ "WARNING:root:group__thatgroup.xml:
ignoring brief description containing multiple paragraphs. Please modify your markup to remove any block elements from the following: <p>Function that's in a group</p><p>Lines of detailed description that get merged to the brief for no freaking reason.</p>"
])
@unittest.skipUnless(LooseVersion(doxygen_version()) >= LooseVersion("1.8.16"),
~cjwatson / blog.git / commitdiff