Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Render newlines as separate paragraphs #380

Merged
merged 1 commit into from
Jun 1, 2018
Merged

Render newlines as separate paragraphs #380

merged 1 commit into from
Jun 1, 2018

Conversation

praetorian20
Copy link
Contributor

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>

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>
@vermeeren vermeeren self-assigned this Jun 1, 2018
@vermeeren vermeeren added enhancement Improvements, additions (also cosmetics) code Source code labels Jun 1, 2018
@vermeeren
Copy link
Collaborator

Thanks for the very detailed commit message/info, reminds me of kernel.org commits. :)

Will release 4.9.0 with this in a bit.

@vermeeren vermeeren merged commit 1206eea into breathe-doc:master Jun 1, 2018
vermeeren added a commit that referenced this pull request Jun 1, 2018
vermeeren added a commit that referenced this pull request Jun 4, 2018
Render newlines as separate paragraphs
vermeeren added a commit that referenced this pull request Jun 4, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
code Source code enhancement Improvements, additions (also cosmetics)
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants