Skip to content

Commit

Permalink
fix: use arguments to \par if available
Browse files Browse the repository at this point in the history
Nerixyz authored and alandefreitas committed Dec 24, 2024
1 parent f92f1f2 commit 03d1a75
Showing 5 changed files with 187 additions and 16 deletions.
40 changes: 24 additions & 16 deletions src/lib/AST/ParseJavadoc.cpp
Original file line number Diff line number Diff line change
@@ -1026,22 +1026,30 @@ visitBlockCommandComment(
visitChildren(C->getParagraph());
if(! paragraph.children.empty())
{
// the first TextComment is the heading text
doc::String text(std::move(
paragraph.children.front()->string));

// VFALCO Unfortunately clang puts at least
// one space in front of the text, which seems
// incorrect.
auto const s = trim(text);
if(s.size() != text.size())
text = s;

doc::Heading heading(std::move(text));
jd_.emplace_back(std::move(heading));

// remaining TextComment, if any
paragraph.children.erase(paragraph.children.begin());
if (C->getNumArgs() > 0)
{
jd_.emplace_back(doc::Heading(C->getArgText(0).str()));
}
else
{
// the first TextComment is the heading text
doc::String text(std::move(
paragraph.children.front()->string));

// VFALCO Unfortunately clang puts at least
// one space in front of the text, which seems
// incorrect.
auto const s = trim(text);
if(s.size() != text.size())
text = s;

doc::Heading heading(std::move(text));
jd_.emplace_back(std::move(heading));

// remaining TextComment, if any
paragraph.children.erase(paragraph.children.begin());
}

if(! paragraph.children.empty())
jd_.emplace_back(std::move(paragraph));
}
51 changes: 51 additions & 0 deletions test-files/golden-tests/para-3.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
= Reference
:mrdocs:

[#index]
== Global namespace

=== Functions
[cols=2]
|===
| Name | Description

| <<#my_function,`my&lowbar;function`>>
| A function

|===

[#my_function]
== my&lowbar;function

A function

=== Synopsis

Declared in `&lt;para&hyphen;3&period;cpp&gt;`

[source,cpp,subs="verbatim,replacements,macros,-callouts"]
----
void
my&lowbar;function();
----

=== Description


=== A heading&period;
Some text&period;

More text&period;&period;&period;

Another paragraph
Next line


=== Exception safety
No&hyphen;throw guarantee&period;





[.small]#Created with https://www.mrdocs.com[MrDocs]#
16 changes: 16 additions & 0 deletions test-files/golden-tests/para-3.cpp
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
/**
* \brief A function
*
* \par
* A heading.
* Some text.
*
* More text...
*
* Another paragraph
* Next line
*
* \par Exception safety
* No-throw guarantee.
*/
void my_function();
67 changes: 67 additions & 0 deletions test-files/golden-tests/para-3.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,67 @@
<html lang="en">
<head>
<title>Reference</title>
</head>
<body>
<div>
<h1>Reference</h1>
<div>
<div>
<h2 id="index">Global namespace</h2>
</div>
<h2>Functions</h2>
<table style="table-layout: fixed; width: 100%;">
<thead>
<tr>
<th>Name</th><th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="#my_function"><code>my_function</code></a> </td><td><span><span>A function</span></span>
</td></tr>
</tbody>
</table>
</div>
<div>
<div>
<h2 id="my_function">my_function</h2>
<div>
<span><span>A function</span></span>

</div>
</div>
<div>
<h3>Synopsis</h3>
<div>
Declared in <code>&lt;para-3.cpp&gt;</code></div>
<pre>
<code class="source-code cpp">
void
my_function();
</code>
</pre>
</div>
<div>
<h3>Description</h3>
<h3>A heading.</h3>
<p><span>Some text.</span></p>

<p><span>More text...</span></p>

<p><span>Another paragraph</span> <span>Next line</span></p>

<h3>Exception safety</h3>
<p><span>No-throw guarantee.</span></p>



</div>
</div>

</div>
<div>
<h4>Created with <a href="https://www.mrdocs.com">MrDocs</a></h4>
</div>
</body>
</html>
29 changes: 29 additions & 0 deletions test-files/golden-tests/para-3.xml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
<?xml version="1.0" encoding="UTF-8"?>
<mrdocs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc">
<namespace id="//////////////////////////8=">
<function name="my_function" id="jv2AC4inoS2L4+tVOPxfYiZpb3g=">
<file path="para-3.cpp" line="16"/>
<doc>
<brief>
<text>A function</text>
</brief>
<head>A heading.</head>
<para>
<text> Some text.</text>
</para>
<para>
<text>More text...</text>
</para>
<para>
<text>Another paragraph</text>
<text> Next line</text>
</para>
<head>Exception safety</head>
<para>
<text>No-throw guarantee.</text>
</para>
</doc>
</function>
</namespace>
</mrdocs>

0 comments on commit 03d1a75

Please sign in to comment.