More detailed Primitive.toChar conversion documentation (#2807)

runtime/src/main/kotlin/kotlin/Primitives.kt

@@ -197,7 +197,10 @@ public final class Byte private constructor() : Number(), Comparable<Byte> {
     /**
      * Converts this [Byte] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value sign-extended to 16 bits.
+     * If this value is non-negative, the resulting `Char` code is equal to this value.
+     *
+     * The least significant 8 bits of the resulting `Char` code are the same as the bits of this `Byte` value,
+     * whereas the most significant 8 bits are filled with the sign bit of this value.
      */
     @TypedIntrinsic(IntrinsicType.SIGN_EXTEND)
     external public override fun toChar(): Char
@@ -206,8 +209,8 @@ public final class Byte private constructor() : Number(), Comparable<Byte> {
      *
      * The resulting `Short` value represents the same numerical value as this `Byte`.
      *
-     * The least significant 8 bits of the resulting `Short` value are the same as the binary representation of this `Byte` value,
+     * The least significant 8 bits of the resulting `Short` value are the same as the bits of this `Byte` value,
-     * whereas the most significant 8 bits are filled with the bit sign of this value.
+     * whereas the most significant 8 bits are filled with the sign bit of this value.
      */
     @TypedIntrinsic(IntrinsicType.SIGN_EXTEND)
     external public override fun toShort(): Short
@@ -216,8 +219,8 @@ public final class Byte private constructor() : Number(), Comparable<Byte> {
      *
      * The resulting `Int` value represents the same numerical value as this `Byte`.
      *
-     * The least significant 8 bits of the resulting `Int` value are the same as the binary representation of this `Byte` value,
+     * The least significant 8 bits of the resulting `Int` value are the same as the bits of this `Byte` value,
-     * whereas the most significant 24 bits are filled with the bit sign of this value.
+     * whereas the most significant 24 bits are filled with the sign bit of this value.
      */
     @TypedIntrinsic(IntrinsicType.SIGN_EXTEND)
     external public override fun toInt(): Int
@@ -226,8 +229,8 @@ public final class Byte private constructor() : Number(), Comparable<Byte> {
      *
      * The resulting `Long` value represents the same numerical value as this `Byte`.
      *
-     * The least significant 8 bits of the resulting `Long` value are the same as the binary representation of this `Byte` value,
+     * The least significant 8 bits of the resulting `Long` value are the same as the bits of this `Byte` value,
-     * whereas the most significant 56 bits are filled with the bit sign of this value.
+     * whereas the most significant 56 bits are filled with the sign bit of this value.
      */
     @TypedIntrinsic(IntrinsicType.SIGN_EXTEND)
     external public override fun toLong(): Long
@@ -486,7 +489,8 @@ public final class Short private constructor() : Number(), Comparable<Short> {
     /**
      * Converts this [Short] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value.
+     * The resulting `Char` code is equal to this value reinterpreted as an unsigned number,
+     * i.e. it has the same binary representation as this `Short`.
      */
     @TypedIntrinsic(IntrinsicType.ZERO_EXTEND)
     external public override fun toChar(): Char
@@ -499,8 +503,8 @@ public final class Short private constructor() : Number(), Comparable<Short> {
      *
      * The resulting `Int` value represents the same numerical value as this `Short`.
      *
-     * The least significant 16 bits of the resulting `Int` value are the same as the binary representation of this `Short` value,
+     * The least significant 16 bits of the resulting `Int` value are the same as the bits of this `Short` value,
-     * whereas the most significant 16 bits are filled with the bit sign of this value.
+     * whereas the most significant 16 bits are filled with the sign bit of this value.
      */
     @TypedIntrinsic(IntrinsicType.SIGN_EXTEND)
     external public override fun toInt(): Int
@@ -509,8 +513,8 @@ public final class Short private constructor() : Number(), Comparable<Short> {
      *
      * The resulting `Long` value represents the same numerical value as this `Short`.
      *
-     * The least significant 16 bits of the resulting `Long` value are the same as the binary representation of this `Short` value,
+     * The least significant 16 bits of the resulting `Long` value are the same as the bits of this `Short` value,
-     * whereas the most significant 48 bits are filled with the bit sign of this value.
+     * whereas the most significant 48 bits are filled with the sign bit of this value.
      */
     @TypedIntrinsic(IntrinsicType.SIGN_EXTEND)
     external public override fun toLong(): Long
@@ -774,7 +778,10 @@ public final class Int private constructor() : Number(), Comparable<Int> {
     /**
      * Converts this [Int] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value truncated to 16 bits.
+     * If this value is in the range of `Char` codes `Char.MIN_VALUE..Char.MAX_VALUE`,
+     * the resulting `Char` code is equal to this value.
+     *
+     * The resulting `Char` code is represented by the least significant 16 bits of this `Int` value.
      */
     @TypedIntrinsic(IntrinsicType.INT_TRUNCATE)
     external public override fun toChar(): Char
@@ -797,8 +804,8 @@ public final class Int private constructor() : Number(), Comparable<Int> {
      *
      * The resulting `Long` value represents the same numerical value as this `Int`.
      *
-     * The least significant 32 bits of the resulting `Long` value are the same as the binary representation of this `Int` value,
+     * The least significant 32 bits of the resulting `Long` value are the same as the bits of this `Int` value,
-     * whereas the most significant 32 bits are filled with the bit sign of this value.
+     * whereas the most significant 32 bits are filled with the sign bit of this value.
      */
     @TypedIntrinsic(IntrinsicType.SIGN_EXTEND)
     external public override fun toLong(): Long
@@ -1064,7 +1071,10 @@ public final class Long private constructor() : Number(), Comparable<Long> {
     /**
      * Converts this [Long] value to [Char].
      *
-     * Returns the `Char` with the numeric value equal to this value truncated to 16 bits.
+     * If this value is in the range of `Char` codes `Char.MIN_VALUE..Char.MAX_VALUE`,
+     * the resulting `Char` code is equal to this value.
+     *
+     * The resulting `Char` code is represented by the least significant 16 bits of this `Long` value.
      */
     @TypedIntrinsic(IntrinsicType.INT_TRUNCATE)
     external public override fun toChar(): Char