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

+
+