From 4c66c1c13796423c52949be62f88e9521ab1f12b Mon Sep 17 00:00:00 2001
From: Abduqodiri Qurbonzoda <abduqodiri.qurbonzoda@jetbrains.com>
Date: Fri, 16 Apr 2021 04:55:58 +0300
Subject: [PATCH] [K/N] Fix Primitive.shl/shr/ushr doc

---
 .../src/main/kotlin/kotlin/Primitives.kt      | 48 ++++++++++++++++---
 1 file changed, 42 insertions(+), 6 deletions(-)

diff --git a/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt b/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt
index 56c9891e108..e2a2577732e 100644
--- a/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt
+++ b/kotlin-native/runtime/src/main/kotlin/kotlin/Primitives.kt
@@ -829,15 +829,33 @@ public final class Int private constructor() : Number(), Comparable<Int> {
     @TypedIntrinsic(IntrinsicType.UNARY_MINUS)
     external public operator fun unaryMinus(): Int
 
-    /** Shifts this value left by the [bitCount] number of bits. */
+    /**
+     * Shifts this value left by the [bitCount] number of bits.
+     *
+     * Note that only the five lowest-order bits of the [bitCount] are used as the shift distance.
+     * The shift distance actually used is therefore always in the range `0..31`.
+     */
     @TypedIntrinsic(IntrinsicType.SHL)
     external public infix fun shl(bitCount: Int): Int
-    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit. */
+
+    /**
+     * Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit.
+     *
+     * Note that only the five lowest-order bits of the [bitCount] are used as the shift distance.
+     * The shift distance actually used is therefore always in the range `0..31`.
+     */
     @TypedIntrinsic(IntrinsicType.SHR)
     external public infix fun shr(bitCount: Int): Int
-    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros. */
+
+    /**
+     * Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros.
+     *
+     * Note that only the five lowest-order bits of the [bitCount] are used as the shift distance.
+     * The shift distance actually used is therefore always in the range `0..31`.
+     */
     @TypedIntrinsic(IntrinsicType.USHR)
     external public infix fun ushr(bitCount: Int): Int
+
     /** Performs a bitwise AND operation between the two values. */
     @TypedIntrinsic(IntrinsicType.AND)
     external public infix fun and(other: Int): Int
@@ -1172,15 +1190,33 @@ public final class Long private constructor() : Number(), Comparable<Long> {
         return LongRange(this, other.toLong())
     }
 
-    /** Shifts this value left by the [bitCount] number of bits. */
+    /**
+     * Shifts this value left by the [bitCount] number of bits.
+     *
+     * Note that only the six lowest-order bits of the [bitCount] are used as the shift distance.
+     * The shift distance actually used is therefore always in the range `0..63`.
+     */
     @TypedIntrinsic(IntrinsicType.SHL)
     external public infix fun shl(bitCount: Int): Long
-    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit. */
+
+    /**
+     * Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with copies of the sign bit.
+     *
+     * Note that only the six lowest-order bits of the [bitCount] are used as the shift distance.
+     * The shift distance actually used is therefore always in the range `0..63`.
+     */
     @TypedIntrinsic(IntrinsicType.SHR)
     external public infix fun shr(bitCount: Int): Long
-    /** Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros. */
+
+    /**
+     * Shifts this value right by the [bitCount] number of bits, filling the leftmost bits with zeros.
+     *
+     * Note that only the six lowest-order bits of the [bitCount] are used as the shift distance.
+     * The shift distance actually used is therefore always in the range `0..63`.
+     */
     @TypedIntrinsic(IntrinsicType.USHR)
     external public infix fun ushr(bitCount: Int): Long
+
     /** Performs a bitwise AND operation between the two values. */
     @TypedIntrinsic(IntrinsicType.AND)
     external public infix fun and(other: Long): Long