feat: 'Default arguments' -> 'Default parameters' (#4833)

* 'Default arguments' -> 'Parameters with default values'. And lambda is not a parameter but an argument

Summarization of the team discussion:
- It's definitely ok to call it "optional parameters", but unfortunately
  it's not a wide-spread term
- It's ok to say it in full "parameters with default values"
- It's ok to say "default value" (if it's clear from the context)
- "default parameters" and "default arguments" are slightly problematic
  and it's better to avoid them

Discussion link:
https://jetbrains.slack.com/archives/C06E082M6/p1746713347805569

The commit fixes two problems:
1. Avoid using "default arguments" and "default parameters"
2. Lambda is not a parameter. It's an expression, and it's an argument
   that corresponds to a parameter with functional type.

* Update anchors: #default-arguments -> #parameters-with-default-values

I missed some anchors in the previous commit

* Update all the remaining 'default arguments'

See the commit before the previous for motivation

* chore: add new term in compiler's guide mention

* update: replace mentions of optional parameters for consistency

* update: replace with parameters with default values

* chore: fix typo

---------

Co-authored-by: alepedroza <[email protected]>

Author: nikitabobko

docs/topics/coding-conventions.md

@@ -1128,7 +1128,7 @@ class Point(val x: Double, val y: Double) {
 ```
 
 If you have an object with multiple overloaded constructors that don't call different superclass constructors and
-can't be reduced to a single constructor with default argument values, prefer to replace the overloaded constructors with
+can't be reduced to a single constructor including parameters with default values, prefer to replace the overloaded constructors with
 factory functions.
 
 ### Platform types

docs/topics/collection-parts.md

@@ -120,7 +120,7 @@ fun main() {
 ```
 {kotlin-runnable="true" kotlin-min-compiler-version="1.3"}
 
-`windowed()` provides more flexibility with optional parameters:
+`windowed()` provides more flexibility regarding parameters with default values:
 
 * `step` defines a distance between first elements of two adjacent windows. By default the value is 1, so the result contains windows starting from all elements. If you increase the step to 2, you will receive only windows starting from odd elements: first, third, and so on.
 * `partialWindows` includes windows of smaller sizes that start from the elements at the end of the collection. For example, if you request windows of three elements, you can't build them for the last two elements. Enabling `partialWindows` in this case includes two more lists of sizes 2 and 1.

docs/topics/collection-transformations.md

@@ -244,8 +244,8 @@ strings: [`joinToString()`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.
 `joinToString()` builds a single `String` from the collection elements based on the provided arguments.
 `joinTo()` does the same but appends the result to the given [`Appendable`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.text/-appendable/index.html) object.
 
-When called with the default arguments, the functions return the result similar to calling `toString()` on the collection:
-a `String` of elements' string representations separated by commas with spaces. 
+When called with the parameters' default values, the functions return the result similar to calling `toString()` on the collection:
+a `String` of elements' string representations separated by commas with spaces.
 
 ```kotlin
 

docs/topics/compatibility-guides/compatibility-guide-22.md

@@ -190,20 +190,20 @@ perspective (for example, from Java) is out of the scope of this document.
 >
 > - 2.2.0: report an error when accessing private types or members from non-private inline functions
 
-### Forbid non-local returns in default argument lambdas
+### Forbid non-local returns in lambdas used as parameter's default value
 
 > **Issue**: [KTLC-286](https://youtrack.jetbrains.com/issue/KTLC-286)
 >
 > **Component**: Core language
 >
 > **Incompatible change type**: source
 >
-> **Short summary**: Non-local return statements are no longer allowed in lambdas used as default arguments.
-> This pattern previously compiled but led to runtime crashes. To migrate, rewrite the lambda to avoid non-local returns or move the logic outside the default argument.
+> **Short summary**: Non-local return statements are no longer allowed in lambdas used as parameter's default value.
+> This pattern previously compiled but led to runtime crashes. To migrate, rewrite the lambda to avoid non-local returns or move the logic outside the default value.
 >
 > **Deprecation cycle**:
 >
-> - 2.2.0: report an error for non-local returns in lambdas used as default argument values
+> - 2.2.0: report an error for non-local returns in lambdas used as parameter's default value
 
 ## Standard library
 

docs/topics/exceptions.md

@@ -459,11 +459,11 @@ creating a hierarchy of exceptions can help making the code clearer and more spe
 You can achieve this by using an [abstract class](classes.md#abstract-classes) or a
 [sealed class](sealed-classes.md#constructors) as a base for common exception features and creating specific 
 subclasses for detailed exception types.
-Additionally, custom exceptions with optional parameters offer flexibility, allowing initialization with varied messages,
+Additionally, custom exceptions including parameters with default values offer flexibility, allowing initialization with varied messages,
 which enables more granular error handling.
 
 Let's look at an example using the sealed class `AccountException` as the base for an exception hierarchy, 
-and class `APIKeyExpiredException`, a subclass, which showcases the use of optional parameters for improved exception detail:
+and class `APIKeyExpiredException`, a subclass, which showcases the use of parameters with default values for improved exception detail:
 
 ```kotlin
 //sampleStart

docs/topics/functions.md

@@ -40,10 +40,10 @@ fun powerOf(
 ) { /*...*/ }
 ```
 
-### Default arguments
+### Parameters with default values
 
-Function parameters can have default values, which are used when you skip the corresponding argument. This reduces the number
-of overloads:
+Function parameters can have default values, which are used when you skip the corresponding argument.
+This reduces the number of overloads:
 
 ```kotlin
 fun read(
@@ -53,6 +53,8 @@ fun read(
 ) { /*...*/ }
 ```
 
+Such parameters are also referred to as _optional parameters_.
+
 A default value is set by appending `=` to the type.
 
 Overriding methods always use the base method's default parameter values.
@@ -68,7 +70,7 @@ class B : A() {
 }
 ```
 
-If a default parameter precedes a parameter with no default value, the default value can only be used by calling
+If a parameter with default value precedes a parameter with no default value, the default value can only be used by calling
 the function with [named arguments](#named-arguments):
 
 ```kotlin
@@ -80,8 +82,8 @@ fun foo(
 foo(baz = 1) // The default value bar = 0 is used
 ```
 
-If the last argument after default parameters is a [lambda](lambdas.md#lambda-expression-syntax),
-you can pass it either as a named argument or [outside the parentheses](lambdas.md#passing-trailing-lambdas):
+If the last parameter after all parameters with default values has a functional type,
+then you can pass the corresponding [lambda](lambdas.md#lambda-expression-syntax) argument either as a named argument or [outside the parentheses](lambdas.md#passing-trailing-lambdas):
 
 ```kotlin
 fun foo(
@@ -247,7 +249,7 @@ for the call). Infix functions must meet the following requirements:
 * They must be member functions or [extension functions](extensions.md).
 * They must have a single parameter.
 * The parameter must not [accept variable number of arguments](#variable-number-of-arguments-varargs) and must have
-no [default value](#default-arguments).
+no [default value](#parameters-with-default-values).
 
 ```kotlin
 infix fun Int.shl(x: Int): Int { ... }

docs/topics/gsoc-2023.md

@@ -138,7 +138,7 @@ but the support for code that uses composition instead of inheritance has yet to
 
 The main problem of working with code that heavily uses composition is parameter forwarding.
 In particular:
-* The IDE doesn't suggest completing parameter declarations that can be forwarded as arguments to other functions that currently use default arguments.
+* The IDE doesn't suggest completing parameter declarations that can be forwarded as arguments to other functions that currently use default parameter values.
 * The IDE doesn't rename the chain of forwarded parameters.
 * The IDE doesn't provide any quick-fixes that fill in all the required arguments with parameters that can be forwarded.
 

docs/topics/js/js-interop.md

@@ -92,9 +92,9 @@ external class MyClass {
 }
 ```
 
-### Declare optional parameters
+### Declare parameters with default values
 
-If you are writing an external declaration for a JavaScript function which has an optional parameter, use `definedExternally`.
+If you are writing an external declaration for a JavaScript function which has a parameter with a default value, use `definedExternally`.
 This delegates the generation of the default values to the JavaScript function itself:
 
 ```kotlin
@@ -133,7 +133,7 @@ class Bar : Foo() {
 There are some limitations:
 
 - When a function of an external base class is overloaded by signature, you can't override it in a derived class.
-- You can't override a function with default arguments.
+- You can't override a function including parameters with default values.
 - Non-external classes can't be extended by external classes.
 
 ### external interfaces

docs/topics/jvm/comparison-to-java.md

@@ -45,7 +45,7 @@ Kotlin fixes a series of issues that Java suffers from:
 * [Data classes](data-classes.md)
 * [Coroutines](coroutines-overview.md)
 * [Top-level functions](functions.md)
-* [Default arguments](functions.md#default-arguments)
+* [Parameters with default values](functions.md#parameters-with-default-values)
 * [Named parameters](functions.md#named-arguments)
 * [Infix functions](functions.md#infix-notation)
 * [Expect and actual declarations](https://www.jetbrains.com/help/kotlin-multiplatform-dev/multiplatform-expect-actual.html)

docs/topics/jvm/java-to-kotlin-nullability-guide.md

@@ -216,7 +216,7 @@ findOrder()?.customer?.let(::processCustomer)
 
 ## Default values instead of null
 
-Checking for `null` is often used in combination with [setting the default value](functions.md#default-arguments)
+Checking for `null` is often used in combination with [setting the default value](functions.md#parameters-with-default-values)
 in case the null check is successful.
 
 The Java code with a null check: