From 1cc1ad5e20db85a438e8ee818e2e4d984b49926f Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 6 Dec 2017 21:22:43 +0100 Subject: [PATCH] doxygen: test and document behavior with code blocks inside lists. It was asserting when wrongly-delimited code block was inside a list. --- doc/doxygen.rst | 38 ++++++++++++++++++++++++ doxygen/dox2html5.py | 1 + doxygen/test/contents_code/index.html | 2 +- doxygen/test/contents_code/input.dox | 28 +++++++++++++++++ doxygen/test/contents_code/warnings.html | 3 +- 5 files changed, 70 insertions(+), 2 deletions(-) diff --git a/doc/doxygen.rst b/doc/doxygen.rst index 2a697f13..f2379c1a 100644 --- 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++ + + /** + + */ + + .. raw:: html + + + .. 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 0b975d27..6cfe2b65 100755 --- 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 d0515d80..f52c31d6 100644 --- a/doxygen/test/contents_code/index.html +++ b/doxygen/test/contents_code/index.html @@ -44,7 +44,7 @@ // but has a lot of trailing whitespace which should be removed }

Look:

void foo() { return; }

A paragraph following a one line snippet should not be merged with it.

void foo() { return; }

This one also not.

#include <cmath>
 
-void bar() { return; }

And this should not produce a warning.

Another paragraph.

+void bar() { return; }

And this should not produce a warning.

Another paragraph.

Code block inside a list (has to be done using HTML):

diff --git a/doxygen/test/contents_code/input.dox b/doxygen/test/contents_code/input.dox index c85d051a..e4cab6c1 100644 --- 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): + + + */ /** @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 + // hello again + @endcode + */ diff --git a/doxygen/test/contents_code/warnings.html b/doxygen/test/contents_code/warnings.html index c94a2b1b..21bd1f40 100644 --- a/doxygen/test/contents_code/warnings.html +++ b/doxygen/test/contents_code/warnings.html @@ -39,7 +39,8 @@ 
// Code without language
 // description

A paragraph.

Multi=line
-code=that is a part of a paragraph.
Code that has unrecognizable format.
+code=that is a part of a paragraph.
Code that has unrecognizable format.

Improper code block inside a list that needs to be extracted out:

-- 2.30.2