From 16ea2bd8374fffb437e99b72991181abb8bffd73 Mon Sep 17 00:00:00 2001 From: alandefreitas Date: Mon, 13 Jan 2025 12:22:36 -0300 Subject: [PATCH] render orphan @par headings Render @par headings when the @par has no children paragraphs #feat fix #787 --- src/lib/AST/ParseJavadoc.cpp | 24 +-- test-files/golden-tests/javadoc/par-1.adoc | 166 ++++++++++++++++++ test-files/golden-tests/javadoc/par-1.cpp | 43 +++++ test-files/golden-tests/javadoc/par-1.html | 164 +++++++++++++++++ test-files/golden-tests/javadoc/par-1.xml | 60 +++++++ .../golden-tests/snippets/is_prime.adoc | 3 + .../golden-tests/snippets/is_prime.html | 1 + test-files/golden-tests/snippets/is_prime.xml | 1 + 8 files changed, 452 insertions(+), 10 deletions(-) create mode 100644 test-files/golden-tests/javadoc/par-1.adoc create mode 100644 test-files/golden-tests/javadoc/par-1.cpp create mode 100644 test-files/golden-tests/javadoc/par-1.html create mode 100644 test-files/golden-tests/javadoc/par-1.xml diff --git a/src/lib/AST/ParseJavadoc.cpp b/src/lib/AST/ParseJavadoc.cpp index f4fc9cb01..fcb800c90 100644 --- a/src/lib/AST/ParseJavadoc.cpp +++ b/src/lib/AST/ParseJavadoc.cpp @@ -1233,24 +1233,26 @@ visitBlockCommandComment( doc::Paragraph paragraph; auto scope = enterScope(paragraph); visitChildren(C->getParagraph()); - if(! paragraph.children.empty()) + if (C->getNumArgs() > 0) { - if (C->getNumArgs() > 0) - { - jd_.emplace_back(doc::Heading(C->getArgText(0).str())); - } - else + jd_.emplace_back(doc::Heading(C->getArgText(0).str())); + } + if (!paragraph.children.empty()) + { + // the first TextComment is the heading text + if (C->getNumArgs() == 0) { - // 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()) + if (auto const s = trim(text); + s.size() != text.size()) + { text = s; + } doc::Heading heading(std::move(text)); jd_.emplace_back(std::move(heading)); @@ -1259,8 +1261,10 @@ visitBlockCommandComment( paragraph.children.erase(paragraph.children.begin()); } - if(! paragraph.children.empty()) + if (!paragraph.children.empty()) + { jd_.emplace_back(std::move(paragraph)); + } } return; } diff --git a/test-files/golden-tests/javadoc/par-1.adoc b/test-files/golden-tests/javadoc/par-1.adoc new file mode 100644 index 000000000..0398d0715 --- /dev/null +++ b/test-files/golden-tests/javadoc/par-1.adoc @@ -0,0 +1,166 @@ += Reference +:mrdocs: + +[#index] +== Global namespace + + +=== Functions + +[cols=2] +|=== +| Name | Description + +| <> +| Brief + + + +| <> +| Brief + + + +| <> +| Brief + + + +| <> +| Brief + + + +|=== + +[#f1] +== f1 + + +Brief + + + +=== Synopsis + + +Declared in `<par‐1.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +void +f1(); +---- + +=== Description + + + +=== Custom par + +Paragraph 1 + +[,cpp] +---- +void f1(); +---- + + +[#f2] +== f2 + + +Brief + + + +=== Synopsis + + +Declared in `<par‐1.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +void +f2(); +---- + +=== Description + + + +=== Custom par + +Paragraph 2 + +[,cpp] +---- +void f2(); +---- + + +[#f3] +== f3 + + +Brief + + + +=== Synopsis + + +Declared in `<par‐1.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +void +f3(); +---- + +=== Description + + + +=== Custom par + +[,cpp] +---- +void f3(); +---- + + +[#f4] +== f4 + + +Brief + + + +=== Synopsis + + +Declared in `<par‐1.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +void +f4(); +---- + +=== Description + + + +=== Custom par + +[,cpp] +---- +void f4(); +---- + + + + +[.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/javadoc/par-1.cpp b/test-files/golden-tests/javadoc/par-1.cpp new file mode 100644 index 000000000..768c2ba68 --- /dev/null +++ b/test-files/golden-tests/javadoc/par-1.cpp @@ -0,0 +1,43 @@ +/** Brief + + @par Custom par + Paragraph 1 + + @code + void f1(); + @endcode + + */ +void f1(); + +/** Brief + + @par Custom par + + Paragraph 2 + + @code + void f2(); + @endcode + + */ +void f2(); + +/** Brief + + @par Custom par + @code + void f3(); + @endcode + */ +void f3(); + +/** Brief + + @par Custom par + + @code + void f4(); + @endcode + */ +void f4(); \ No newline at end of file diff --git a/test-files/golden-tests/javadoc/par-1.html b/test-files/golden-tests/javadoc/par-1.html new file mode 100644 index 000000000..846612718 --- /dev/null +++ b/test-files/golden-tests/javadoc/par-1.html @@ -0,0 +1,164 @@ + + +Reference + + +
+

Reference

+
+
+

Global namespace

+
+

Functions

+ + + + + + + + + + + + + +
NameDescription
f1

Brief

+ +
f2

Brief

+ +
f3

Brief

+ +
f4

Brief

+ +
+
+
+
+

f1

+
+

Brief

+ + +
+
+
+

Synopsis

+
+Declared in <par-1.cpp>
+
+
+void
+f1();
+
+
+
+
+

Description

+

Custom par

+

Paragraph 1

+ +void f1(); + + + +
+
+
+
+

f2

+
+

Brief

+ + +
+
+
+

Synopsis

+
+Declared in <par-1.cpp>
+
+
+void
+f2();
+
+
+
+
+

Description

+

Custom par

+

Paragraph 2

+ +void f2(); + + + +
+
+
+
+

f3

+
+

Brief

+ + +
+
+
+

Synopsis

+
+Declared in <par-1.cpp>
+
+
+void
+f3();
+
+
+
+
+

Description

+

Custom par

+ +void f3(); + + + +
+
+
+
+

f4

+
+

Brief

+ + +
+
+
+

Synopsis

+
+Declared in <par-1.cpp>
+
+
+void
+f4();
+
+
+
+
+

Description

+

Custom par

+ +void f4(); + + + +
+
+ +
+
+

Created with MrDocs

+
+ + \ No newline at end of file diff --git a/test-files/golden-tests/javadoc/par-1.xml b/test-files/golden-tests/javadoc/par-1.xml new file mode 100644 index 000000000..97801a74e --- /dev/null +++ b/test-files/golden-tests/javadoc/par-1.xml @@ -0,0 +1,60 @@ + + + + + + + + Brief + + Custom par + + Paragraph 1 + + + void f1(); + + + + + + + + Brief + + Custom par + + Paragraph 2 + + + void f2(); + + + + + + + + Brief + + Custom par + + void f3(); + + + + + + + + Brief + + Custom par + + void f4(); + + + + + diff --git a/test-files/golden-tests/snippets/is_prime.adoc b/test-files/golden-tests/snippets/is_prime.adoc index 23c1a4466..d1b871ada 100644 --- a/test-files/golden-tests/snippets/is_prime.adoc +++ b/test-files/golden-tests/snippets/is_prime.adoc @@ -40,6 +40,9 @@ is_prime(unsigned long long n) noexcept; === Description + +=== Complexity + Linear in n. diff --git a/test-files/golden-tests/snippets/is_prime.html b/test-files/golden-tests/snippets/is_prime.html index 7b47fa30f..91257d738 100644 --- a/test-files/golden-tests/snippets/is_prime.html +++ b/test-files/golden-tests/snippets/is_prime.html @@ -46,6 +46,7 @@

Synopsis

Description

+

Complexity

Linear in n.

diff --git a/test-files/golden-tests/snippets/is_prime.xml b/test-files/golden-tests/snippets/is_prime.xml index cd4d30651..fa1e5d1be 100644 --- a/test-files/golden-tests/snippets/is_prime.xml +++ b/test-files/golden-tests/snippets/is_prime.xml @@ -14,6 +14,7 @@ Return true if a number is prime. + Complexity Linear in n.