From 98d31a18130eeca9b004649158710d86709dd013 Mon Sep 17 00:00:00 2001
From: Abduqodiri Qurbonzoda <abduqodiri.qurbonzoda@jetbrains.com>
Date: Mon, 18 Jan 2021 00:50:15 +0300
Subject: [PATCH] Expand KDoc of inc() and dec() operators #KT-43701

---
 core/builtins/native/kotlin/Char.kt           | 13 ++-
 core/builtins/native/kotlin/Primitives.kt     | 84 ++++++++++++++++---
 generators/builtins/primitives.kt             | 27 ++++--
 generators/builtins/unsignedTypes.kt          |  8 +-
 .../runtime/src/main/kotlin/kotlin/Char.kt    | 12 ++-
 .../src/main/kotlin/kotlin/Primitives.kt      | 72 +++++++++++++---
 libraries/stdlib/js-ir/builtins/Char.kt       | 13 ++-
 libraries/stdlib/js-ir/builtins/Primitives.kt | 70 +++++++++++++---
 libraries/stdlib/js-ir/runtime/long.kt        | 12 ++-
 .../samples/test/samples/misc/builtins.kt     | 46 ++++++++++
 libraries/stdlib/unsigned/src/kotlin/UByte.kt | 13 ++-
 libraries/stdlib/unsigned/src/kotlin/UInt.kt  | 13 ++-
 libraries/stdlib/unsigned/src/kotlin/ULong.kt | 13 ++-
 .../stdlib/unsigned/src/kotlin/UShort.kt      | 13 ++-
 libraries/stdlib/wasm/builtins/kotlin/Char.kt | 12 ++-
 .../stdlib/wasm/builtins/kotlin/Primitives.kt | 72 +++++++++++++---
 16 files changed, 418 insertions(+), 75 deletions(-)
 create mode 100644 libraries/stdlib/samples/test/samples/misc/builtins.kt

diff --git a/core/builtins/native/kotlin/Char.kt b/core/builtins/native/kotlin/Char.kt
index f642ea93f67..f1a62566501 100644
--- a/core/builtins/native/kotlin/Char.kt
+++ b/core/builtins/native/kotlin/Char.kt
@@ -38,9 +38,18 @@ public class Char private constructor() : Comparable<Char> {
     /** Subtracts the other Int value from this value resulting a Char. */
     public operator fun minus(other: Int): Char
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public operator fun inc(): Char
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Char
 
     /** Creates a range from this value to the specified [other] value. */
diff --git a/core/builtins/native/kotlin/Primitives.kt b/core/builtins/native/kotlin/Primitives.kt
index cc164d0f333..934879a9d54 100644
--- a/core/builtins/native/kotlin/Primitives.kt
+++ b/core/builtins/native/kotlin/Primitives.kt
@@ -173,10 +173,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. */
@@ -411,10 +421,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. */
@@ -647,10 +667,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. */
@@ -918,10 +948,20 @@ public class Long private constructor() : Number(), Comparable<Long> {
     @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(): Long
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public operator fun dec(): Long
+
     /** Returns this value. */
     public operator fun unaryPlus(): Long
     /** Returns the negative of this value. */
@@ -1208,10 +1248,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. */
@@ -1449,10 +1499,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. */
diff --git a/generators/builtins/primitives.kt b/generators/builtins/primitives.kt
index e111d1efa2b..82096714896 100644
--- a/generators/builtins/primitives.kt
+++ b/generators/builtins/primitives.kt
@@ -20,9 +20,7 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
             "div",
             "rem",
         )
-        internal val unaryOperators: Map<String, String> = mapOf(
-            "inc" to "Increments this value.",
-            "dec" to "Decrements this value.",
+        internal val unaryPlusMinusOperators: Map<String, String> = mapOf(
             "unaryPlus" to "Returns this value.",
             "unaryMinus" to "Returns the negative of this value.")
         internal val shiftOperators: Map<String, String> = mapOf(
@@ -47,6 +45,18 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
                 """
         }
 
+        internal fun incDecOperatorsDoc(name: String): String {
+            val diff = if (name == "inc") "incremented" else "decremented"
+
+            return """
+                /**
+                 * Returns this value $diff by one.
+                 *
+                 * @sample samples.misc.Builtins.$name
+                 */
+                """
+        }
+
         internal fun binaryOperatorDoc(operator: String, operand1: PrimitiveType, operand2: PrimitiveType): String = when (operator) {
             "plus" -> "Adds the other value to this value."
             "minus" -> "Subtracts the other value from this value."
@@ -239,9 +249,14 @@ class GeneratePrimitives(out: PrintWriter) : BuiltInsSourceGenerator(out) {
     }
 
     private fun generateUnaryOperators(kind: PrimitiveType) {
-        for ((name, doc) in unaryOperators) {
-            val returnType = if (kind in listOf(PrimitiveType.SHORT, PrimitiveType.BYTE, PrimitiveType.CHAR) &&
-                                 name in listOf("unaryPlus", "unaryMinus")) "Int" else kind.capitalized
+        for (name in listOf("inc", "dec")) {
+            out.println(incDecOperatorsDoc(name).replaceIndent("    "))
+            out.println("    public operator fun $name(): ${kind.capitalized}")
+            out.println()
+        }
+
+        for ((name, doc) in unaryPlusMinusOperators) {
+            val returnType = if (kind in listOf(PrimitiveType.SHORT, PrimitiveType.BYTE, PrimitiveType.CHAR)) "Int" else kind.capitalized
             out.println("    /** $doc */")
             out.println("    public operator fun $name(): $returnType")
         }
diff --git a/generators/builtins/unsignedTypes.kt b/generators/builtins/unsignedTypes.kt
index c7ab3e00fe6..0364d5fddd0 100644
--- a/generators/builtins/unsignedTypes.kt
+++ b/generators/builtins/unsignedTypes.kt
@@ -204,14 +204,12 @@ class UnsignedTypeGenerator(val type: UnsignedType, out: PrintWriter) : BuiltIns
 
 
     private fun generateUnaryOperators() {
-        for ((name, doc) in GeneratePrimitives.unaryOperators) {
-            if (name in listOf("unaryPlus", "unaryMinus")) continue
-            out.println("    /** $doc */")
+        for (name in listOf("inc", "dec")) {
+            out.println(GeneratePrimitives.incDecOperatorsDoc(name).replaceIndent("    "))
             out.println("    @kotlin.internal.InlineOnly")
             out.println("    public inline operator fun $name(): $className = $className(data.$name())")
-
+            out.println()
         }
-        out.println()
     }
 
     private fun generateRangeTo() {
diff --git a/kotlin-native/runtime/src/main/kotlin/kotlin/Char.kt b/kotlin-native/runtime/src/main/kotlin/kotlin/Char.kt
index 5b2d6c18186..b92438c69b1 100644
--- a/kotlin-native/runtime/src/main/kotlin/kotlin/Char.kt
+++ b/kotlin-native/runtime/src/main/kotlin/kotlin/Char.kt
@@ -32,10 +32,18 @@ public class Char private constructor() : Comparable<Char> {
     public inline operator fun minus(other: Int): Char =
             (this.code - other).toChar()
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @TypedIntrinsic(IntrinsicType.INC)
     external public operator fun inc(): Char
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @TypedIntrinsic(IntrinsicType.DEC)
     external public operator fun dec(): Char
 
diff --git a/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt b/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt
index 5e794d24228..e6099789389 100644
--- a/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt
+++ b/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt
@@ -179,10 +179,18 @@ public final class Byte private constructor() : Number(), Comparable<Byte> {
     public inline operator fun rem(other: Double): Double =
             this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @TypedIntrinsic(IntrinsicType.INC)
     external public operator fun inc(): Byte
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @TypedIntrinsic(IntrinsicType.DEC)
     external public operator fun dec(): Byte
     /** Returns this value. */
@@ -450,10 +458,18 @@ public final class Short private constructor() : Number(), Comparable<Short> {
     public inline operator fun rem(other: Double): Double =
             this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @TypedIntrinsic(IntrinsicType.INC)
     external public operator fun inc(): Short
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @TypedIntrinsic(IntrinsicType.DEC)
     external public operator fun dec(): Short
     /** Returns this value. */
@@ -720,10 +736,18 @@ public final class Int private constructor() : Number(), Comparable<Int> {
     public inline operator fun rem(other: Double): Double =
             this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @TypedIntrinsic(IntrinsicType.INC)
     external public operator fun inc(): Int
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @TypedIntrinsic(IntrinsicType.DEC)
     external public operator fun dec(): Int
     /** Returns this value. */
@@ -1014,10 +1038,18 @@ public final class Long private constructor() : Number(), Comparable<Long> {
     public inline operator fun rem(other: Double): Double =
             this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @TypedIntrinsic(IntrinsicType.INC)
     external public operator fun inc(): Long
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @TypedIntrinsic(IntrinsicType.DEC)
     external public operator fun dec(): Long
     /** Returns this value. */
@@ -1334,10 +1366,18 @@ public final class Float private constructor() : Number(), Comparable<Float> {
     public inline operator fun rem(other: Double): Double =
             this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @TypedIntrinsic(IntrinsicType.INC)
     external public operator fun inc(): Float
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @TypedIntrinsic(IntrinsicType.DEC)
     external public operator fun dec(): Float
     /** Returns this value. */
@@ -1612,10 +1652,18 @@ public final class Double private constructor() : Number(), Comparable<Double> {
     @TypedIntrinsic(IntrinsicType.SIGNED_REM)
     external public operator fun rem(other: Double): Double
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @TypedIntrinsic(IntrinsicType.INC)
     external public operator fun inc(): Double
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @TypedIntrinsic(IntrinsicType.DEC)
     external public operator fun dec(): Double
     /** Returns this value. */
diff --git a/libraries/stdlib/js-ir/builtins/Char.kt b/libraries/stdlib/js-ir/builtins/Char.kt
index 3c5b55a6284..600ff0c5bcd 100644
--- a/libraries/stdlib/js-ir/builtins/Char.kt
+++ b/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. */
diff --git a/libraries/stdlib/js-ir/builtins/Primitives.kt b/libraries/stdlib/js-ir/builtins/Primitives.kt
index f7fc205d7cf..002d02f7641 100644
--- a/libraries/stdlib/js-ir/builtins/Primitives.kt
+++ b/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. */
diff --git a/libraries/stdlib/js-ir/runtime/long.kt b/libraries/stdlib/js-ir/runtime/long.kt
index 3c8db977c1d..e1738de723f 100644
--- a/libraries/stdlib/js-ir/runtime/long.kt
+++ b/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. */
diff --git a/libraries/stdlib/samples/test/samples/misc/builtins.kt b/libraries/stdlib/samples/test/samples/misc/builtins.kt
new file mode 100644
index 00000000000..3267f801289
--- /dev/null
+++ b/libraries/stdlib/samples/test/samples/misc/builtins.kt
@@ -0,0 +1,46 @@
+/*
+ * Copyright 2010-2021 JetBrains s.r.o. and Kotlin Programming Language contributors.
+ * Use of this source code is governed by the Apache 2.0 license that can be found in the license/LICENSE.txt file.
+ */
+
+package samples.misc
+
+import samples.*
+
+class Builtins {
+
+    @Sample
+    fun inc() {
+        val a = 3
+        val b = a.inc()
+        assertPrints(a, "3")
+        assertPrints(b, "4")
+
+        var x = 3
+        val y = x++
+        assertPrints(x, "4")
+        assertPrints(y, "3")
+
+        val z = ++x
+        assertPrints(x, "5")
+        assertPrints(z, "5")
+    }
+
+    @Sample
+    fun dec() {
+        val a = 3
+        val b = a.dec()
+        assertPrints(a, "3")
+        assertPrints(b, "2")
+
+        var x = 3
+        val y = x--
+        assertPrints(x, "2")
+        assertPrints(y, "3")
+
+        val z = --x
+        assertPrints(x, "1")
+        assertPrints(z, "1")
+    }
+}
+
diff --git a/libraries/stdlib/unsigned/src/kotlin/UByte.kt b/libraries/stdlib/unsigned/src/kotlin/UByte.kt
index 369cdab8688..d1545d4b8cf 100644
--- a/libraries/stdlib/unsigned/src/kotlin/UByte.kt
+++ b/libraries/stdlib/unsigned/src/kotlin/UByte.kt
@@ -217,10 +217,19 @@ public value class UByte @PublishedApi internal constructor(@PublishedApi intern
     @kotlin.internal.InlineOnly
     public inline fun mod(other: ULong): ULong = this.toULong().mod(other)
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun inc(): UByte = UByte(data.inc())
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun dec(): UByte = UByte(data.dec())
 
diff --git a/libraries/stdlib/unsigned/src/kotlin/UInt.kt b/libraries/stdlib/unsigned/src/kotlin/UInt.kt
index b1c4f942446..1247e831a7e 100644
--- a/libraries/stdlib/unsigned/src/kotlin/UInt.kt
+++ b/libraries/stdlib/unsigned/src/kotlin/UInt.kt
@@ -217,10 +217,19 @@ public value class UInt @PublishedApi internal constructor(@PublishedApi interna
     @kotlin.internal.InlineOnly
     public inline fun mod(other: ULong): ULong = this.toULong().mod(other)
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun inc(): UInt = UInt(data.inc())
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun dec(): UInt = UInt(data.dec())
 
diff --git a/libraries/stdlib/unsigned/src/kotlin/ULong.kt b/libraries/stdlib/unsigned/src/kotlin/ULong.kt
index 51ee0920b00..05616fd276e 100644
--- a/libraries/stdlib/unsigned/src/kotlin/ULong.kt
+++ b/libraries/stdlib/unsigned/src/kotlin/ULong.kt
@@ -217,10 +217,19 @@ public value class ULong @PublishedApi internal constructor(@PublishedApi intern
     @kotlin.internal.InlineOnly
     public inline fun mod(other: ULong): ULong = rem(other)
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun inc(): ULong = ULong(data.inc())
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun dec(): ULong = ULong(data.dec())
 
diff --git a/libraries/stdlib/unsigned/src/kotlin/UShort.kt b/libraries/stdlib/unsigned/src/kotlin/UShort.kt
index 95a79d09898..6dc01c64d1f 100644
--- a/libraries/stdlib/unsigned/src/kotlin/UShort.kt
+++ b/libraries/stdlib/unsigned/src/kotlin/UShort.kt
@@ -217,10 +217,19 @@ public value class UShort @PublishedApi internal constructor(@PublishedApi inter
     @kotlin.internal.InlineOnly
     public inline fun mod(other: ULong): ULong = this.toULong().mod(other)
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun inc(): UShort = UShort(data.inc())
-    /** Decrements this value. */
+
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     @kotlin.internal.InlineOnly
     public inline operator fun dec(): UShort = UShort(data.dec())
 
diff --git a/libraries/stdlib/wasm/builtins/kotlin/Char.kt b/libraries/stdlib/wasm/builtins/kotlin/Char.kt
index 49391beb5c9..0cec64ff764 100644
--- a/libraries/stdlib/wasm/builtins/kotlin/Char.kt
+++ b/libraries/stdlib/wasm/builtins/kotlin/Char.kt
@@ -43,11 +43,19 @@ public class Char private constructor(public val value: Char) : Comparable<Char>
     public inline operator fun minus(other: Int): Char =
         (this.toInt() - other).toChar()
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public inline operator fun inc(): Char =
         (this.toInt() + 1).toChar()
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public inline operator fun dec(): Char =
         (this.toInt() - 1).toChar()
 
diff --git a/libraries/stdlib/wasm/builtins/kotlin/Primitives.kt b/libraries/stdlib/wasm/builtins/kotlin/Primitives.kt
index bc585e0b1d6..47eb15c8e5a 100644
--- a/libraries/stdlib/wasm/builtins/kotlin/Primitives.kt
+++ b/libraries/stdlib/wasm/builtins/kotlin/Primitives.kt
@@ -209,11 +209,19 @@ public class Byte private constructor(public val value: Byte) : Number(), Compar
     public inline operator fun rem(other: Double): Double =
         this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public inline operator fun inc(): Byte =
         (this + 1).toByte()
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public inline operator fun dec(): Byte =
         (this - 1).toByte()
 
@@ -545,11 +553,19 @@ public class Short private constructor(public val value: Short) : Number(), Comp
     public inline operator fun rem(other: Double): Double =
         this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public inline operator fun inc(): Short =
         (this + 1).toShort()
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public inline operator fun dec(): Short =
         (this - 1).toShort()
 
@@ -885,11 +901,19 @@ public class Int private constructor(val value: Int) : Number(), Comparable<Int>
     public inline operator fun rem(other: Double): Double =
         this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public inline operator fun inc(): Int =
         this + 1
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     // TODO: Fix test compiler/testData/codegen/box/functions/invoke/invoke.kt with inline dec
     public operator fun dec(): Int =
         this - 1
@@ -1275,11 +1299,19 @@ public class Long private constructor(val value: Long) : Number(), Comparable<Lo
     public inline operator fun rem(other: Double): Double =
         this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public inline operator fun inc(): Long =
         this + 1L
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public inline operator fun dec(): Long =
         this - 1L
 
@@ -1651,11 +1683,19 @@ public class Float private constructor(public val value: Float) : Number(), Comp
     public inline operator fun rem(other: Double): Double =
         this.toDouble() % other
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public inline operator fun inc(): Float =
         this + 1.0f
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public inline operator fun dec(): Float =
         this - 1.0f
 
@@ -1957,11 +1997,19 @@ public class Double private constructor(public val value: Double) : Number(), Co
     public operator fun rem(other: Double): Double =
         this - (wasm_f64_nearest(this / other) * other)
 
-    /** Increments this value. */
+    /**
+     * Returns this value incremented by one.
+     *
+     * @sample samples.misc.Builtins.inc
+     */
     public inline operator fun inc(): Double =
         this + 1.0
 
-    /** Decrements this value. */
+    /**
+     * Returns this value decremented by one.
+     *
+     * @sample samples.misc.Builtins.dec
+     */
     public inline operator fun dec(): Double =
         this - 1.0