From a64809cfaba737a6b46ee2e7036cc553d123fe6a Mon Sep 17 00:00:00 2001
From: Ashish Sadanandan <ashish.sadanandan@gmail.com>
Date: Thu, 31 May 2018 12:41:56 -0600
Subject: [PATCH] Render newlines as separate paragraphs

Line breaks in Doxygen documentation are not being rendered correctly.
Given the following C++ class definition

    /*!
     * @brief Lorem ipsum dolor sit amet
     */
    class foo
    {
    public:
       /* Fields */
       uint8_t   bar; /*!< @brief consectetur adipiscing elit
 	<br>Range: 0 .. 10<br>Default: 0*/
    }; // class foo

The corresponding XML output for the `bar` data member is

    <memberdef kind="variable" id="classfoo_1a1c39cf8cc2d68f0a7bf308aa34c3b5ba" prot="public" static="no" mutable="no">
      <type>uint8_t</type>
      <definition>uint8_t foo::bar</definition>
      <argsstring></argsstring>
      <name>bar</name>
      <briefdescription>
 <para>consectetur adipiscing elit <linebreak/>
 Range: 0 .. 10<linebreak/>
 Default: 0 </para>        </briefdescription>
      <detaileddescription>
      </detaileddescription>
      <inbodydescription>
      </inbodydescription>
      <location file="test.h" line="94" bodyfile="test.h" bodystart="93" bodyend="-1"/>
    </memberdef>

The `<linebreak/>` tags, which appear as newline characters in the node
argument's text in the call to `SphinxRenderer.visit_unicode`, do not get
rendered as paragraphs. The corresponding Sphinx HTML is

    <dd><p>consectetur adipiscing elit
    Range: 0 .. 10
    Default: 0 </p>
    </dd></dl>

This commit wraps each line in multiline comments in a paragraph so it gets
rendered correctly. After applying this change, the Sphinx HTML is rendered as
follows

    <dd><p>consectetur adipiscing elit <p>Range: 0 .. 10</p>
    <p>Default: 0 </p>
    </p>
    </dd></dl>
---
 breathe/renderer/sphinxrenderer.py | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/breathe/renderer/sphinxrenderer.py b/breathe/renderer/sphinxrenderer.py
index c576d4f5..4b072897 100644
--- a/breathe/renderer/sphinxrenderer.py
+++ b/breathe/renderer/sphinxrenderer.py
@@ -431,11 +431,16 @@ def visit_unicode(self, node):
         # We counter that second issue slightly by allowing through single white spaces
         #
         if node.strip():
-            if "<linebreak>" not in node:
-                return [self.node_factory.Text(node)]
-            # Render lines as paragraphs because RST doesn't have line breaks.
-            return [self.node_factory.paragraph('', '', self.node_factory.Text(line))
-                    for line in node.split("<linebreak>")]
+            delimiter = None
+            if "<linebreak>" in node:
+                delimiter = "<linebreak>"
+            elif "\n" in node:
+                delimiter = "\n"
+            if delimiter:
+                # Render lines as paragraphs because RST doesn't have line breaks.
+                return [self.node_factory.paragraph('', '', self.node_factory.Text(line))
+                        for line in node.split(delimiter) if line.strip()]
+            return [self.node_factory.Text(node)]
         if node == six.u(" "):
             return [self.node_factory.Text(node)]
         return []