From ca8a688ce904dcf8a087eceec65cf836ec148b69 Mon Sep 17 00:00:00 2001 From: Gennaro Prota Date: Wed, 22 Apr 2026 11:12:18 +0200 Subject: [PATCH] fix: stop auto-brief extraction at headings When a symbol's documentation begins with a `@par Title` block (with no front matter text before it), parsing emits a `HeadingBlock` for the title followed by a `ParagraphBlock` for the body. The auto-brief pass walked past the heading looking for the first paragraph, promoted the `@par` body to the brief, and left the title rendered as a section with no content. The fix is to stop iterating at the first HeadingBlock: content under a heading is the body of that section, not the symbol's introductory prose. This is tightly scoped---`HeadingBlock` is only emitted from `@par` today--- and preserves the existing behavior when a front matter is present. The commit adds a regression test covering both shapes (no front matter, and explicit brief paragraph before the `@par` section). Closes issue #1162. --- .../Finalizers/DocCommentFinalizer.cpp | 9 ++ .../golden-tests/javadoc/paragraph/par-1.adoc | 40 +++++++++ .../golden-tests/javadoc/paragraph/par-1.cpp | 20 ++++- .../golden-tests/javadoc/paragraph/par-1.html | 45 +++++++++- .../golden-tests/javadoc/paragraph/par-1.xml | 89 +++++++++++++++++++ 5 files changed, 201 insertions(+), 2 deletions(-) diff --git a/src/lib/Metadata/Finalizers/DocCommentFinalizer.cpp b/src/lib/Metadata/Finalizers/DocCommentFinalizer.cpp index 497808085d..d9e63a38d4 100644 --- a/src/lib/Metadata/Finalizers/DocCommentFinalizer.cpp +++ b/src/lib/Metadata/Finalizers/DocCommentFinalizer.cpp @@ -475,6 +475,15 @@ setAutoBrief(DocComment& doc) const for (auto it = doc.Document.begin(); it != doc.Document.end();) { + // A heading marks the start of a section (as of writing + // this, the only way to produce one is an @par with an + // explicit title). Anything that follows is the body of + // that section, not the symbol's introductory prose, so + // stop looking for a brief here. See issue #1162. + if ((*it)->Kind == doc::BlockKind::Heading) + { + return; + } if (auto& block = *it; block->Kind == doc::BlockKind::Paragraph) { diff --git a/test-files/golden-tests/javadoc/paragraph/par-1.adoc b/test-files/golden-tests/javadoc/paragraph/par-1.adoc index 58f40b65b8..d1b23bebe2 100644 --- a/test-files/golden-tests/javadoc/paragraph/par-1.adoc +++ b/test-files/golden-tests/javadoc/paragraph/par-1.adoc @@ -17,6 +17,10 @@ | Brief | link:#f4[`f4`] | Brief +| link:#f5[`f5`] +| +| link:#f6[`f6`] +| A function. |=== [#f1] @@ -107,5 +111,41 @@ f4(); ---- void f4(); ---- +[#f5] +== f5 + +=== Synopsis + +Declared in `<par‐1.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +void +f5(); +---- + +=== Custom par + +Paragraph 5 + +[#f6] +== f6 + +A function. + +=== Synopsis + +Declared in `<par‐1.cpp>` + +[source,cpp,subs="verbatim,replacements,macros,-callouts"] +---- +void +f6(); +---- + +=== Custom par + +Paragraph 6 + [.small]#Created with https://www.mrdocs.com[MrDocs]# diff --git a/test-files/golden-tests/javadoc/paragraph/par-1.cpp b/test-files/golden-tests/javadoc/paragraph/par-1.cpp index 768c2ba68c..be731a1710 100644 --- a/test-files/golden-tests/javadoc/paragraph/par-1.cpp +++ b/test-files/golden-tests/javadoc/paragraph/par-1.cpp @@ -40,4 +40,22 @@ void f3(); void f4(); @endcode */ -void f4(); \ No newline at end of file +void f4(); + +// No front matter: the body of @par must not be promoted +// to an auto-brief (issue #1162). +/** + + @par Custom par + Paragraph 5 + */ +void f5(); + +// Same shape as f5 but with explicit front matter: the front +// matter becomes the brief, the @par section is preserved. +/** A function. + + @par Custom par + Paragraph 6 + */ +void f6(); \ No newline at end of file diff --git a/test-files/golden-tests/javadoc/paragraph/par-1.html b/test-files/golden-tests/javadoc/paragraph/par-1.html index 0ff0e4f3d8..1a8eb33d1b 100644 --- a/test-files/golden-tests/javadoc/paragraph/par-1.html +++ b/test-files/golden-tests/javadoc/paragraph/par-1.html @@ -24,7 +24,9 @@

f1 Brief f2 Brief f3 Brief -f4 Brief +f4 Brief +f5 +f6 A function. @@ -123,6 +125,47 @@

void f4(); +
+
+

+f5

+
+
+

+Synopsis

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

+Custom par

+

Paragraph 5

+
+
+
+
+

+f6

+
+

A function.

+
+
+
+

+Synopsis

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

+Custom par

+

Paragraph 6

+
+