Docs: preserve empty lines in the generated documentation to separate summary and paragraphs in the body.

libraries/tools/kotlin-stdlib-gen/src/templates/Generators.kt

@@ -13,6 +13,7 @@ fun generators(): List<GenericFunction> {
         doc(Sets) {
             """
             Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -53,6 +54,7 @@ fun generators(): List<GenericFunction> {
         doc(Sets) {
             """
             Returns a set containing all elements of the original set and then the given [element] if it isn't already in this set.
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -164,6 +166,7 @@ fun generators(): List<GenericFunction> {
             """
             Returns a set containing all elements of the original set and the given [elements] array,
             which aren't already in this set.
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -220,6 +223,7 @@ fun generators(): List<GenericFunction> {
             """
             Returns a set containing all elements of the original set and the given [elements] sequence,
             which aren't already in this set.
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -255,6 +259,7 @@ fun generators(): List<GenericFunction> {
         doc(Sets) {
             """
             Returns a set containing all elements of the original set except the given [element].
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -283,6 +288,7 @@ fun generators(): List<GenericFunction> {
         doc(Sets) {
             """
             Returns a set containing all elements of the original set except the given [element].
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -329,6 +335,7 @@ fun generators(): List<GenericFunction> {
         doc(Sets) {
             """
             Returns a set containing all elements of the original set except the elements contained in the given [elements] collection.
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -386,6 +393,7 @@ fun generators(): List<GenericFunction> {
         doc(Sets) {
             """
             Returns a set containing all elements of the original set except the elements contained in the given [elements] array.
+
             The returned set preserves the element iteration order of the original set.
             """
         }
@@ -437,6 +445,7 @@ fun generators(): List<GenericFunction> {
         doc(Sets) {
             """
             Returns a set containing all elements of the original set except the elements contained in the given [elements] sequence.
+
             The returned set preserves the element iteration order of the original set.
             """
         }

libraries/tools/kotlin-stdlib-gen/src/templates/Mapping.kt

@@ -294,7 +294,9 @@ fun mapping(): List<GenericFunction> {
             """
             Groups ${f.element.pluralize()} of the original ${f.collection} by the key returned by the given [keySelector] function
             applied to each ${f.element} and returns a map where each group key is associated with a list of corresponding ${f.element.pluralize()}.
+
             The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
+
             @sample test.collections.CollectionTest.groupBy
             """
         }
@@ -315,6 +317,7 @@ fun mapping(): List<GenericFunction> {
             applied to each ${f.element} and puts to the [destination] map each group key associated with a list of corresponding ${f.element.pluralize()}.
 
             @return The [destination] map.
+
             @sample test.collections.CollectionTest.groupBy
             """
         }
@@ -340,7 +343,9 @@ fun mapping(): List<GenericFunction> {
             Groups values returned by the [valueTransform] function applied to each ${f.element} of the original ${f.collection}
             by the key returned by the given [keySelector] function applied to the ${f.element}
             and returns a map where each group key is associated with a list of corresponding values.
+
             The returned map preserves the entry iteration order of the keys produced from the original ${f.collection}.
+
             @sample test.collections.CollectionTest.groupByKeysAndValues
             """
         }
@@ -364,7 +369,9 @@ fun mapping(): List<GenericFunction> {
             Groups values returned by the [valueTransform] function applied to each ${f.element} of the original ${f.collection}
             by the key returned by the given [keySelector] function applied to the ${f.element}
             and puts to the [destination] map each group key associated with a list of corresponding values.
+
             @return The [destination] map.
+
             @sample test.collections.CollectionTest.groupByKeysAndValues
             """
         }

libraries/tools/kotlin-stdlib-gen/src/templates/Ranges.kt

@@ -50,6 +50,7 @@ fun ranges(): List<GenericFunction> {
         doc {
             """
             Returns a progression from this value down to the specified [to] value with the step -1.
+
             The [to] value has to be less than this value.
             """
         }
@@ -86,6 +87,7 @@ fun ranges(): List<GenericFunction> {
         doc {
             """
             Returns a range from this value up to but excluding the specified [to] value.
+
             ${ if (elementType == toType) "The [to] value must be greater than [$elementType.MIN_VALUE]." else "" }
             """
         }

libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt

@@ -10,6 +10,7 @@ fun sets(): List<GenericFunction> {
         doc { f ->
             """
             Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}.
+
             The returned set preserves the element iteration order of the original ${f.collection}.
             """
         }
@@ -97,6 +98,7 @@ fun sets(): List<GenericFunction> {
         doc { f ->
             """
             Returns a set containing all distinct elements from both collections.
+
             The returned set preserves the element iteration order of the original ${f.collection}.
             Those elements of the [other] collection that are unique are iterated in the end
             in the order of the [other] collection.
@@ -118,6 +120,7 @@ fun sets(): List<GenericFunction> {
         doc { f ->
             """
             Returns a set containing all elements that are contained by both this set and the specified collection.
+
             The returned set preserves the element iteration order of the original ${f.collection}.
             """
         }
@@ -137,6 +140,7 @@ fun sets(): List<GenericFunction> {
         doc { f ->
             """
             Returns a set containing all elements that are contained by this ${f.collection} and not contained by the specified collection.
+
             The returned set preserves the element iteration order of the original ${f.collection}.
             """
         }

libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt

@@ -24,6 +24,7 @@ fun snapshots(): List<GenericFunction> {
         doc { f ->
             """
             Returns a [Set] of all ${f.element.pluralize()}.
+
             The returned set preserves the element iteration order of the original ${f.collection}.
             """
         }
@@ -172,7 +173,9 @@ fun snapshots(): List<GenericFunction> {
             """
             Returns a [Map] containing key-value pairs provided by [transform] function
             applied to ${f.element.pluralize()} of the given ${f.collection}.
+
             If any of two pairs would have the same key the last one gets added to the map.
+
             The returned map preserves the entry iteration order of the original ${f.collection}.
             """
         }
@@ -215,6 +218,7 @@ fun snapshots(): List<GenericFunction> {
             """
             Populates and returns the [destination] mutable map with key-value pairs
             provided by [transform] function applied to each ${f.element} of the given ${f.collection}.
+
             If any of two pairs would have the same key the last one gets added to the map.
             """
         }
@@ -236,7 +240,9 @@ fun snapshots(): List<GenericFunction> {
             """
             Returns a [Map] containing the ${f.element.pluralize()} from the given ${f.collection} indexed by the key
             returned from [keySelector] function applied to each ${f.element}.
+
             If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
+
             The returned map preserves the entry iteration order of the original ${f.collection}.
             """
         }
@@ -286,6 +292,7 @@ fun snapshots(): List<GenericFunction> {
             Populates and returns the [destination] mutable map with key-value pairs,
             where key is provided by the [keySelector] function applied to each ${f.element} of the given ${f.collection}
             and value is the ${f.element} itself.
+
             If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
             """
         }
@@ -307,7 +314,9 @@ fun snapshots(): List<GenericFunction> {
         doc { f ->
             """
             Returns a [Map] containing the values provided by [valueTransform] and indexed by [keySelector] functions applied to ${f.element.pluralize()} of the given ${f.collection}.
+
             If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
+
             The returned map preserves the entry iteration order of the original ${f.collection}.
             """
         }
@@ -359,6 +368,7 @@ fun snapshots(): List<GenericFunction> {
             Populates and returns the [destination] mutable map with key-value pairs,
             where key is provided by the [keySelector] function and
             and value is provided by the [valueTransform] function applied to ${f.element.pluralize()} of the given ${f.collection}.
+
             If any two ${f.element.pluralize()} would have the same key returned by [keySelector] the last one gets added to the map.
             """
         }

libraries/tools/kotlin-stdlib-gen/src/templates/engine/Engine.kt

@@ -371,11 +371,8 @@ class GenericFunction(val signature: String, val keyword: String = "fun") {
 
         doc[f]?.let { methodDoc ->
             builder.append("/**\n")
-            StringReader(methodDoc).forEachLine {
-                val line = it.trim()
-                if (!line.isEmpty()) {
-                    builder.append(" * ").append(line).append("\n")
-                }
+            StringReader(methodDoc.trim()).forEachLine { line ->
+                builder.append(" * ").append(line.trim()).append("\n")
             }
             builder.append(" */\n")
         }