Expand KDoc of inc() and dec() operators #KT-43701

libraries/stdlib/js-ir/builtins/Char.kt

@@ -32,9 +32,18 @@ constructor(code: UShort) : Comparable<Char> {
     /** Subtracts the other Int value from this value resulting a Char. */
     public operator fun minus(other: Int): Char = (value - other).toChar()
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Char = (value + 1).toChar()
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Char = (value - 1).toChar()
 
     /** Creates a range from this value to the specified [other] value. */

libraries/stdlib/js-ir/builtins/Primitives.kt

@@ -174,10 +174,20 @@ public class Byte private constructor() : Number(), Comparable<Byte> {
     @SinceKotlin("1.1")
     public operator fun rem(other: Double): Double
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Byte
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Byte
+
     /** Returns this value. */
     public operator fun unaryPlus(): Int
     /** Returns the negative of this value. */
@@ -416,10 +426,20 @@ public class Short private constructor() : Number(), Comparable<Short> {
     @SinceKotlin("1.1")
     public operator fun rem(other: Double): Double
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Short
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Short
+
     /** Returns this value. */
     public operator fun unaryPlus(): Int
     /** Returns the negative of this value. */
@@ -655,10 +675,20 @@ public class Int private constructor() : Number(), Comparable<Int> {
     @SinceKotlin("1.1")
     public operator fun rem(other: Double): Double
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Int
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Int
+
     /** Returns this value. */
     public operator fun unaryPlus(): Int
     /** Returns the negative of this value. */
@@ -946,10 +976,20 @@ public class Float private constructor() : Number(), Comparable<Float> {
     @SinceKotlin("1.1")
     public operator fun rem(other: Double): Double
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Float
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Float
+
     /** Returns this value. */
     public operator fun unaryPlus(): Float
     /** Returns the negative of this value. */
@@ -1192,10 +1232,20 @@ public class Double private constructor() : Number(), Comparable<Double> {
     @SinceKotlin("1.1")
     public operator fun rem(other: Double): Double
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Double
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Double
+
     /** Returns this value. */
     public operator fun unaryPlus(): Double
     /** Returns the negative of this value. */

libraries/stdlib/js-ir/runtime/long.kt

@@ -201,10 +201,18 @@ public class Long internal constructor(
     @SinceKotlin("1.1")
     public inline operator fun rem(other: Double): Double = toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Long = this + 1L
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Long = this - 1L
 
     /** Returns this value. */