KT-11329: improve formatting of KDoc sections

8 files changed, 55 insertions, 6 deletions

diff --git a/core/src/main/kotlin/Formats/StructuredFormatService.kt b/core/src/main/kotlin/Formats/StructuredFormatService.kt
index 15a4dfba..4f64baa1 100644
--- a/core/src/main/kotlin/Formats/StructuredFormatService.kt
+++ b/core/src/main/kotlin/Formats/StructuredFormatService.kt
@@ -256,8 +256,11 @@ abstract class StructuredFormatService(locationService: LocationService,
             }
 
             for (section in content.sections.filter { it.subjectName == null }) {
-                appendLine(to, formatStrong(formatText(section.tag)))
-                appendLine(to, formatText(location, section))
+                val sectionText = buildString {
+                    appendLine(this, formatStrong(formatText(section.tag)))
+                    append(formatText(location, section))
+                }
+                appendParagraph(to, sectionText)
             }
         }
 
diff --git a/core/src/test/kotlin/format/KotlinWebSiteFormatTest.kt b/core/src/test/kotlin/format/KotlinWebSiteFormatTest.kt
index a96139fd..d4738b2f 100644
--- a/core/src/test/kotlin/format/KotlinWebSiteFormatTest.kt
+++ b/core/src/test/kotlin/format/KotlinWebSiteFormatTest.kt
@@ -11,6 +11,10 @@ class KotlinWebSiteFormatTest {
         verifyKWSNodeByName("sample", "foo")
     }
 
+    @Test fun returnTag() {
+        verifyKWSNodeByName("returnTag", "indexOf")
+    }
+
     private fun verifyKWSNodeByName(fileName: String, name: String) {
         verifyOutput("testdata/format/website/$fileName.kt", ".md") { model, output ->
             kwsService.appendNodes(tempLocation, output, model.members.single().members.filter { it.name == name })
diff --git a/core/testdata/format/accessor.md b/core/testdata/format/accessor.md
index 8279f452..eb326727 100644
--- a/core/testdata/format/accessor.md
+++ b/core/testdata/format/accessor.md
@@ -4,11 +4,14 @@
 # x
 
 `var x: String`
+
 **Getter**
 
 The getter returns an empty string.
 
 
+
+
 **Setter**
 
 The setter does nothing.
@@ -16,3 +19,4 @@ The setter does nothing.
 
 
 
+
diff --git a/core/testdata/format/javaSeeTag.html b/core/testdata/format/javaSeeTag.html
index e5e17f6d..3269c5a0 100644
--- a/core/testdata/format/javaSeeTag.html
+++ b/core/testdata/format/javaSeeTag.html
@@ -8,8 +8,8 @@
 <h1>Foo</h1>
 <code><span class="keyword">open</span> <span class="keyword">class </span><span class="identifier">Foo</span></code><br/>
 <p></p>
-<strong>See Also</strong><br/>
-<a href="test/-foo/bar">#bar</a><br/>
+<p><strong>See Also</strong><br/>
+<a href="test/-foo/bar">#bar</a></p>
 <br/>
 <br/>
 <h3>Constructors</h3>
diff --git a/core/testdata/format/javaSpaceInAuthor.md b/core/testdata/format/javaSpaceInAuthor.md
index 4d19ed01..e464f0a0 100644
--- a/core/testdata/format/javaSpaceInAuthor.md
+++ b/core/testdata/format/javaSpaceInAuthor.md
@@ -7,11 +7,13 @@
 
 
 
+
 **Author**
 Dmitry Jemerov
 
 
 
+
 ### Constructors
 
 
diff --git a/core/testdata/format/see.html b/core/testdata/format/see.html
index e5ae4669..e39711bb 100644
--- a/core/testdata/format/see.html
+++ b/core/testdata/format/see.html
@@ -7,10 +7,10 @@
 <h1>quux</h1>
 <a name="$quux()"></a>
 <code><span class="keyword">fun </span><span class="identifier">quux</span><span class="symbol">(</span><span class="symbol">)</span><span class="symbol">: </span><span class="identifier">Unit</span></code><br/>
-<strong>See Also</strong><br/>
+<p><strong>See Also</strong><br/>
 <p><a href="test/foo">foo</a></p>
 <p><a href="test/bar">bar</a></p>
-<br/>
+</p>
 <br/>
 <br/>
 <a href="test/index">test</a>&nbsp;/&nbsp;<a href="test/foo">foo</a><br/>
diff --git a/core/testdata/format/website/returnTag.kt b/core/testdata/format/website/returnTag.kt
new file mode 100644
index 00000000..669c14f9
--- /dev/null
+++ b/core/testdata/format/website/returnTag.kt
@@ -0,0 +1,11 @@
+class Foo
+
+/**
+ * Returns the index within this string of the first occurrence of the specified character, starting from the specified [startIndex].
+ *
+ * @param ignoreCase `true` to ignore character case when matching a character. By default `false`.
+ * @returns An index of the first occurrence of [char] or -1 if none is found.
+ */
+fun Foo.indexOf(char: Char, startIndex: Int = 0, ignoreCase: Boolean = false): Int {
+    return -1
+}
diff --git a/core/testdata/format/website/returnTag.md b/core/testdata/format/website/returnTag.md
new file mode 100644
index 00000000..301635ad
--- /dev/null
+++ b/core/testdata/format/website/returnTag.md
@@ -0,0 +1,25 @@
+---
+title: indexOf - test
+layout: api
+---
+
+<div class='api-docs-breadcrumbs'><a href="test/index">test</a> / <a href="test/index-of">indexOf</a></div>
+
+
+# indexOf
+
+<div class="signature"><code><span class="keyword">fun </span><a href="test/-foo/index"><span class="identifier">Foo</span></a><span class="symbol">.</span><span class="identifier">indexOf</span><span class="symbol">(</span><br/>&nbsp;&nbsp;&nbsp;&nbsp;<span class="parameterName">char</span><span class="symbol">:</span>&nbsp;<span class="identifier">Char</span><span class="symbol">, </span><br/>&nbsp;&nbsp;&nbsp;&nbsp;<span class="parameterName">startIndex</span><span class="symbol">:</span>&nbsp;<span class="identifier">Int</span>&nbsp;<span class="symbol">=</span>&nbsp;0<span class="symbol">, </span><br/>&nbsp;&nbsp;&nbsp;&nbsp;<span class="parameterName">ignoreCase</span><span class="symbol">:</span>&nbsp;<span class="identifier">Boolean</span>&nbsp;<span class="symbol">=</span>&nbsp;false<br/><span class="symbol">)</span><span class="symbol">: </span><span class="identifier">Int</span></code><br/>
+</div>
+
+Returns the index within this string of the first occurrence of the specified character, starting from the specified <a href="test/index-of#$indexOf(Foo, kotlin.Char, kotlin.Int, kotlin.Boolean)/startIndex">startIndex</a>.
+
+
+### Parameters
+
+<code>ignoreCase</code> - <code>true</code> to ignore character case when matching a character. By default <code>false</code>.
+
+**Returns**
+An index of the first occurrence of <a href="test/index-of#$indexOf(Foo, kotlin.Char, kotlin.Int, kotlin.Boolean)/char">char</a> or -1 if none is found.
+
+
+