Document exception thrown for negative n in take/takeLast/drop/dropLast

#KT-29151

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

@@ -52,6 +52,7 @@ object Filtering : TemplateGroupBase() {
             Returns a list containing all elements except first [n] elements.
             """
         }
+        throws("IllegalArgumentException", "if [n] is negative.")
         sample("${sampleClass(f)}.drop")
         returns("List<T>")
         body {
@@ -138,6 +139,7 @@ object Filtering : TemplateGroupBase() {
             Returns a list containing first [n] elements.
             """
         }
+        throws("IllegalArgumentException", "if [n] is negative.")
         sample("${sampleClass(f)}.take")
         returns("List<T>")
         body {
@@ -218,6 +220,7 @@ object Filtering : TemplateGroupBase() {
             Returns a list containing all elements except last [n] elements.
             """
         }
+        throws("IllegalArgumentException", "if [n] is negative.")
         sample("${sampleClass(f)}.drop")
         returns("List<T>")
         body {
@@ -247,6 +250,7 @@ object Filtering : TemplateGroupBase() {
             Returns a list containing last [n] elements.
             """
         }
+        throws("IllegalArgumentException", "if [n] is negative.")
         sample("${sampleClass(f)}.take")
         returns("List<T>")
         specialFor(Strings, CharSequences) {

libraries/tools/kotlin-stdlib-gen/src/templates/dsl/CommonTypes.kt

@@ -137,4 +137,6 @@ enum class SequenceClass {
 }
 
 data class Deprecation(val message: String, val replaceWith: String? = null, val level: DeprecationLevel = DeprecationLevel.WARNING)
-val forBinaryCompatibility = Deprecation("Provided for binary compatibility", level = DeprecationLevel.HIDDEN)
+val forBinaryCompatibility = Deprecation("Provided for binary compatibility", level = DeprecationLevel.HIDDEN)
+
+data class ThrowsException(val exceptionType: String, val reason: String)

libraries/tools/kotlin-stdlib-gen/src/templates/dsl/MemberBuilder.kt

@@ -64,6 +64,7 @@ class MemberBuilder(
     var toNullableT: Boolean = false
 
     var returns: String? = null; private set
+    val throwsExceptions = mutableListOf<ThrowsException>()
     var body: String? = null; private set
     val annotations: MutableList<String> = mutableListOf()
     val suppressions: MutableList<String> = mutableListOf()
@@ -99,6 +100,8 @@ class MemberBuilder(
     @Deprecated("Use specialFor", ReplaceWith("specialFor(*fs) { returns(run(valueBuilder)) }"))
     fun returns(vararg fs: Family, valueBuilder: () -> String) = specialFor(*fs) { returns(run(valueBuilder)) }
 
+    fun throws(exceptionType: String, reason: String) { throwsExceptions += ThrowsException(exceptionType, reason) }
+
     fun typeParam(typeParameterName: String, primary: Boolean = false) {
         typeParams += typeParameterName
         if (primary) {
@@ -300,9 +303,13 @@ class MemberBuilder(
                 builder.append(" *\n")
                 builder.append(" * The operation is ${sequenceClassification.joinToString(" and ") { "_${it}_" }}.\n")
             }
+            if (throwsExceptions.any()) {
+                builder.append(" * \n")
+                throwsExceptions.forEach { (type, reason) -> builder.append(" * @throws $type $reason\n") }
+            }
             if (samples.any()) {
                 builder.append(" * \n")
-                samples.forEach { builder.append(" * @sample $it\n")}
+                samples.forEach { builder.append(" * @sample $it\n") }
             }
             builder.append(" */\n")
         }