From: Vladimír Vondruš <mosra@centrum.cz>
Date: Wed, 6 Dec 2017 13:10:28 +0000 (+0100)
Subject: doxygen: improve heuristics for inline code.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=00b85f43437fc9c125279ec24b4ecd8f9f8b42de;p=blog.git

doxygen: improve heuristics for inline code.

Now it should be finally robust. The test passes again.
---

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index 7af90e00..d8f5f530 100644
--- a/doc/doxygen.rst
+++ b/doc/doxygen.rst
@@ -379,7 +379,10 @@ distinguished from code blocks using the following rules:
 
 -   Code that is delimited from surrounding paragraphs with an empty line is
     considered as block.
--   Code that is not alone in a paragraph is considered as inline.
+-   Code that is coming from ``@include``, ``@snippet`` and related commands
+    that paste external file content is always considered as block.
+-   Code that is coming from ``@code`` and is not alone in a paragraph is
+    considered as inline.
 -   For compatibility reasons, if code that is detected as inline consists of
     more than one line, it's rendered as code block and a warning is printed to
     output.
@@ -424,26 +427,9 @@ aliases in the original ``Doxyfile``:
 
 .. block-warning:: Doxygen limitations
 
-    Due to Doxygen limitations, sometimes a single-line code block coming from
-    ``@skipline`` and related commands is detected as inline code and prepended
-    to the immediately following paragraph. In order to prevent that, add a
-    stray :html:`<p>` tag right
-    after the block:
-
-    .. code:: c++
-
-        /**
-        Text paragraph before a code block.
-
-        @skipline foo
-        <p>
-
-        Next text paragraph after a code block.
-        */
-
-    Besides that, it's not possible to use inline code highlighting in
-    ``@brief`` description. Code placed there is moved by Doxygen to the
-    detailed description.
+    It's not possible to use inline code highlighting in ``@brief``
+    description. Code placed there is moved by Doxygen to the detailed
+    description.
 
 .. block-warning:: Doxygen patches
 
diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 98f6998c..464a951d 100755
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -319,8 +319,14 @@ def parse_desc_internal(state: State, element: ET.Element, trim = True):
 
         elif i.tag == 'programlisting':
             # Seems to be a standalone code paragraph, don't wrap it in <p>
-            # and use <pre>
-            if element.tag == 'para' and (not element.text or not element.text.strip()) and (not i.tail or not i.tail.strip()) and len([listing for listing in element]) == 1:
+            # and use <pre>:
+            # - is either alone in the paragraph, with no text or other
+            #   elements around
+            # - or is a code snippet (filename instead of just .ext). Doxygen
+            #   unfortunately doesn't put @snippet in its own paragraph even
+            #   if it's separated by blank lines. It does so for @include and
+            #   related, though.
+            if element.tag == 'para' and (((not element.text or not element.text.strip()) and (not i.tail or not i.tail.strip()) and len([listing for listing in element]) == 1) or ('filename' in i.attrib and not i.attrib['filename'].startswith('.'))):
                 code_block = True
 
             # Looks like inline code, but has multiple code lines, so it's
@@ -336,7 +342,6 @@ def parse_desc_internal(state: State, element: ET.Element, trim = True):
                 # Doxygen doesn't add a space before <programlisting> if it's
                 # inline, add it manually in case there should be a space
                 # before it. However, it does add a space after it always.
-                # TODO: could this be used to detect the problematic case?
                 if out.parsed and not out.parsed[-1].isspace() and not out.parsed[-1] in '([{':
                     out.parsed += ' '