doxygen: test and document behavior with code blocks inside lists.

It was asserting when wrongly-delimited code block was inside a list.

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index 2a697f1318a2e44c1a71c3d186bd6ce545e0e89e..f2379c1afd4a74f19b7172086eb08dcdc6e85ef0 100644 (file)
--- a/doc/doxygen.rst
+++ b/doc/doxygen.rst
@@ -478,6 +478,44 @@ aliases in the original ``Doxyfile``:
     description. Code placed there is moved by Doxygen to the detailed
     description.
 
+    It's not possible to put a ``@code`` block (delimited by blank lines) to a
+    Markdown list. A workaround is to use explicit HTML markup instead. See
+    `Text content`_ for more information about list behavior.
+
+    .. code-figure::
+
+        .. code:: c++
+
+            /**
+            <ul>
+            <li>
+                A paragraph.
+
+                @code{.cpp}
+                #include <os>
+                @endcode
+            </li>
+            <li>
+                Another paragraph.
+
+                Yet another
+            </li>
+            </ul>
+            */
+
+        .. raw:: html
+
+            <ul>
+              <li>
+                <p>A paragraph.</p>
+                <pre class="m-code"><span class="cp">#include</span> <span class="cpf">&lt;os&gt;</span><span class="cp"></span></pre>
+              </li>
+              <li>
+                <p>Another paragraph.</p>
+                <p>Yet another</p>
+              </li>
+            </ul>
+
 .. block-warning:: Doxygen patches
 
     Note that proper language detection for code snippets requires Doxygen with

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 0b975d2745c8170ffd5126ab77763c8cafa4149f..6cfe2b650f19c3c70ff8bef71466d2884e8d4c23 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -413,6 +413,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
             #
             # Specialization of similar paragraph cleanup code above.
             if code_block:
+                out.is_reasonable_paragraph = False
                 has_block_elements = True
                 out.parsed = out.parsed.rstrip()
                 if not out.parsed:

diff --git a/doxygen/test/contents_code/index.html b/doxygen/test/contents_code/index.html
index d0515d8002992a6431fea7478df0a373a6fe63d6..f52c31d6ec00f9173653acb3d5ed0302aaedf4bd 100644 (file)
--- a/doxygen/test/contents_code/index.html
+++ b/doxygen/test/contents_code/index.html
@@ -44,7 +44,7 @@
     <span class="c1">// but has a lot of trailing whitespace which should be removed</span>
 <span class="p">}</span></pre><p>Look:</p><pre class="m-code"><span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span><span class="p">;</span> <span class="p">}</span></pre><p>A paragraph following a one line snippet should not be merged with it.</p><pre class="m-code"><span class="kt">void</span> <span class="nf">foo</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span><span class="p">;</span> <span class="p">}</span></pre><p>This one also not.</p><pre class="m-code"><span class="cp">#include</span> <span class="cpf">&lt;cmath&gt;</span><span class="cp"></span>
 
-<span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span><span class="p">;</span> <span class="p">}</span></pre><p>And this should not produce a warning.</p><p>Another paragraph.</p>
+<span class="kt">void</span> <span class="nf">bar</span><span class="p">()</span> <span class="p">{</span> <span class="k">return</span><span class="p">;</span> <span class="p">}</span></pre><p>And this should not produce a warning.</p><p>Another paragraph.</p><p>Code block inside a list (has to be done using HTML):</p><ul><li><p>A paragraph.</p><pre class="m-code"><span class="cp">#include</span> <span class="cpf">&lt;os&gt;</span><span class="cp"></span></pre></li><li><p>Another paragraph.</p><p>Yet another</p></li><li>A single paragraph, rendered without the wrapping tag</li></ul>
       </div>
     </div>
   </div>

diff --git a/doxygen/test/contents_code/input.dox b/doxygen/test/contents_code/input.dox
index c85d051a5f123b37681059fc4bfcd802a2b9bf74..e4cab6c167d54d38be97ddea51d5995f183d342d 100644 (file)
--- a/doxygen/test/contents_code/input.dox
+++ b/doxygen/test/contents_code/input.dox
@@ -45,6 +45,25 @@ This one also not.
 And this should not produce a warning.
 
 Another paragraph.
+
+Code block inside a list (has to be done using HTML):
+
+<ul>
+<li>
+    A paragraph.
+
+    @code{.cpp}
+    #include <os>
+    @endcode
+</li>
+<li>
+    Another paragraph.
+
+    Yet another
+</li>
+<li>A single paragraph, rendered without the wrapping tag</li>
+</ul>
+
 */
 
 /** @page warnings Code that produces warnings
@@ -63,4 +82,13 @@ code=that is a part of a paragraph.
 @code{.whatthehell}
 Code that has unrecognizable format.
 @endcode
+
+Improper code block inside a list that needs to be extracted out:
+
+-   A paragraph.
+    @code{.cpp}
+    #include <os>
+    // hello again
+    @endcode
+
 */

diff --git a/doxygen/test/contents_code/warnings.html b/doxygen/test/contents_code/warnings.html
index c94a2b1bb44659106efe36f1668c949c91967e97..21bd1f4012d99ba096b39d7d7a4182512ccdcb41 100644 (file)
--- a/doxygen/test/contents_code/warnings.html
+++ b/doxygen/test/contents_code/warnings.html
@@ -39,7 +39,8 @@
         </h1>
 <pre class="m-code"><span class="c1">// Code without language</span>
 <span class="c1">// description</span></pre><p>A paragraph.</p><pre class="m-code"><span class="na">Multi</span><span class="o">=</span><span class="s">line</span>
-<span class="na">code</span><span class="o">=</span><span class="s">that is a part of a paragraph.</span></pre><pre class="m-code">Code that has unrecognizable format.</pre>
+<span class="na">code</span><span class="o">=</span><span class="s">that is a part of a paragraph.</span></pre><pre class="m-code">Code that has unrecognizable format.</pre><p>Improper code block inside a list that needs to be extracted out:</p><ul><li><p>A paragraph.</p><pre class="m-code"><span class="cp">#include</span> <span class="cpf">&lt;os&gt;</span><span class="cp"></span>
+<span class="c1">// hello again</span></pre></li></ul>
       </div>
     </div>
   </div>