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

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. */

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. */

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")
         }

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() {

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
 

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. */

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. */

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")
+    }
+}
+

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())
 

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())
 

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())
 

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())
 

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()
 

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