Improve documentation for bitops (#16961)

* Improve documentation for bitops

Use func
Use let in runnableExamples

* Remove unnecessary tests

Fix #7587

1 files changed, 131 insertions, 128 deletions

diff --git a/lib/pure/bitops.nim b/lib/pure/bitops.nim
index 9a4a49e9a..2f1fc1814 100644
--- a/lib/pure/bitops.nim
+++ b/lib/pure/bitops.nim
@@ -8,27 +8,27 @@
 #
 
 ## This module implements a series of low level methods for bit manipulation.
-
-## By default, this module use compiler intrinsics where possible to improve performance
-## on supported compilers: ``GCC``, ``LLVM_GCC``, ``CLANG``, ``VCC``, ``ICC``.
 ##
-## The module will fallback to pure nim procs incase the backend is not supported.
+## By default, compiler intrinsics are used where possible to improve performance
+## on supported compilers: `GCC`, `LLVM_GCC`, `CLANG`, `VCC`, `ICC`.
+##
+## The module will fallback to pure nim procs in case the backend is not supported.
 ## You can also use the flag `noIntrinsicsBitOpts` to disable compiler intrinsics.
 ##
-## This module is also compatible with other backends: ``Javascript``, ``Nimscript``
-## as well as the ``compiletime VM``.
+## This module is also compatible with other backends: `JavaScript`, `NimScript`
+## as well as the `compiletime VM`.
 ##
-## As a result of using optimized function/intrinsics some functions can return
+## As a result of using optimized functions/intrinsics, some functions can return
 ## undefined results if the input is invalid. You can use the flag `noUndefinedBitOpts`
 ## to force predictable behaviour for all input, causing a small performance hit.
 ##
-## At this time only `fastLog2`, `firstSetBit, `countLeadingZeroBits`, `countTrailingZeroBits`
-## may return undefined and/or platform dependent value if given invalid input.
+## At this time only `fastLog2`, `firstSetBit`, `countLeadingZeroBits` and `countTrailingZeroBits`
+## may return undefined and/or platform dependent values if given invalid input.
 
 import macros
 import std/private/since
 
-proc bitnot*[T: SomeInteger](x: T): T {.magic: "BitnotI", noSideEffect.}
+func bitnot*[T: SomeInteger](x: T): T {.magic: "BitnotI".}
   ## Computes the `bitwise complement` of the integer `x`.
 
 func internalBitand[T: SomeInteger](x, y: T): T {.magic: "BitandI".}
@@ -89,10 +89,10 @@ template forwardImpl(impl, arg) {.dirty.} =
 
 when defined(nimHasalignOf):
   type BitsRange*[T] = range[0..sizeof(T)*8-1]
-    ## A range with all bit positions for type ``T``
+    ## A range with all bit positions for type `T`.
 
   func bitsliced*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
-    ## Returns an extracted (and shifted) slice of bits from ``v``.
+    ## Returns an extracted (and shifted) slice of bits from `v`.
     runnableExamples:
       doAssert 0b10111.bitsliced(2 .. 4) == 0b101
       doAssert 0b11100.bitsliced(0 .. 2) == 0b100
@@ -104,7 +104,7 @@ when defined(nimHasalignOf):
     (uv shl (upmost - slice.b) shr (upmost - slice.b + slice.a)).T
 
   proc bitslice*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
-    ## Mutates ``v`` into an extracted (and shifted) slice of bits from ``v``.
+    ## Mutates `v` into an extracted (and shifted) slice of bits from `v`.
     runnableExamples:
       var x = 0b101110
       x.bitslice(2 .. 4)
@@ -130,32 +130,32 @@ when defined(nimHasalignOf):
     (bitmask shl (upmost - slice.b + slice.a) shr (upmost - slice.b)).T
 
   proc masked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
-    ## Returns ``v``, with only the ``1`` bits from ``mask`` matching those of
-    ## ``v`` set to 1.
+    ## Returns `v`, with only the `1` bits from `mask` matching those of
+    ## `v` set to 1.
     ##
-    ## Effectively maps to a `bitand` operation.
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
-      var v = 0b0000_0011'u8
+      let v = 0b0000_0011'u8
       doAssert v.masked(0b0000_1010'u8) == 0b0000_0010'u8
 
     bitand(v, mask)
 
   func masked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
-    ## Mutates ``v``, with only the ``1`` bits in the range of ``slice``
-    ## matching those of ``v`` set to 1.
+    ## Returns `v`, with only the `1` bits in the range of `slice`
+    ## matching those of `v` set to 1.
     ##
-    ## Effectively maps to a `bitand` operation.
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
-      var v = 0b0000_1011'u8
+      let v = 0b0000_1011'u8
       doAssert v.masked(1 .. 3) == 0b0000_1010'u8
 
     bitand(v, toMask[T](slice))
 
   proc mask*[T: SomeInteger](v: var T; mask: T) {.inline, since: (1, 3).} =
-    ## Mutates ``v``, with only the ``1`` bits from ``mask`` matching those of
-    ## ``v`` set to 1.
+    ## Mutates `v`, with only the `1` bits from `mask` matching those of
+    ## `v` set to 1.
     ##
-    ## Effectively maps to a `bitand` operation.
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.mask(0b0000_1010'u8)
@@ -164,10 +164,10 @@ when defined(nimHasalignOf):
     v = bitand(v, mask)
 
   proc mask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
-    ## Mutates ``v``, with only the ``1`` bits in the range of ``slice``
-    ## matching those of ``v`` set to 1.
+    ## Mutates `v`, with only the `1` bits in the range of `slice`
+    ## matching those of `v` set to 1.
     ##
-    ## Effectively maps to a `bitand` operation.
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
       var v = 0b0000_1011'u8
       v.mask(1 .. 3)
@@ -176,29 +176,29 @@ when defined(nimHasalignOf):
     v = bitand(v, toMask[T](slice))
 
   func setMasked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
-    ## Returns ``v``, with all the ``1`` bits from ``mask`` set to 1.
+    ## Returns `v`, with all the `1` bits from `mask` set to 1.
     ##
-    ## Effectively maps to a `bitor` operation.
+    ## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
-      var v = 0b0000_0011'u8
+      let v = 0b0000_0011'u8
       doAssert v.setMasked(0b0000_1010'u8) == 0b0000_1011'u8
 
     bitor(v, mask)
 
   func setMasked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
-    ## Returns ``v``, with all the ``1`` bits in the range of ``slice`` set to 1.
+    ## Returns `v`, with all the `1` bits in the range of `slice` set to 1.
     ##
-    ## Effectively maps to a `bitor` operation.
+    ## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
-      var v = 0b0000_0011'u8
+      let v = 0b0000_0011'u8
       doAssert v.setMasked(2 .. 3) == 0b0000_1111'u8
 
     bitor(v, toMask[T](slice))
 
   proc setMask*[T: SomeInteger](v: var T; mask: T) {.inline.} =
-    ## Mutates ``v``, with all the ``1`` bits from ``mask`` set to 1.
+    ## Mutates `v`, with all the `1` bits from `mask` set to 1.
     ##
-    ## Effectively maps to a `bitor` operation.
+    ## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.setMask(0b0000_1010'u8)
@@ -207,9 +207,9 @@ when defined(nimHasalignOf):
     v = bitor(v, mask)
 
   proc setMask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
-    ## Mutates ``v``, with all the ``1`` bits in the range of ``slice`` set to 1.
+    ## Mutates `v`, with all the `1` bits in the range of `slice` set to 1.
     ##
-    ## Effectively maps to a `bitor` operation.
+    ## Effectively maps to a `bitor <#bitor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.setMask(2 .. 3)
@@ -218,29 +218,32 @@ when defined(nimHasalignOf):
     v = bitor(v, toMask[T](slice))
 
   func clearMasked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
-    ## Returns ``v``, with all the ``1`` bits from ``mask`` set to 0.
+    ## Returns `v`, with all the `1` bits from `mask` set to 0.
     ##
-    ## Effectively maps to a `bitand` operation with an *inverted mask.*
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
+    ## with an *inverted mask*.
     runnableExamples:
-      var v = 0b0000_0011'u8
+      let v = 0b0000_0011'u8
       doAssert v.clearMasked(0b0000_1010'u8) == 0b0000_0001'u8
 
     bitand(v, bitnot(mask))
 
   func clearMasked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
-    ## Returns ``v``, with all the ``1`` bits in the range of ``slice`` set to 0.
+    ## Returns `v`, with all the `1` bits in the range of `slice` set to 0.
     ##
-    ## Effectively maps to a `bitand` operation with an *inverted mask.*
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
+    ## with an *inverted mask*.
     runnableExamples:
-      var v = 0b0000_0011'u8
+      let v = 0b0000_0011'u8
       doAssert v.clearMasked(1 .. 3) == 0b0000_0001'u8
 
     bitand(v, bitnot(toMask[T](slice)))
 
   proc clearMask*[T: SomeInteger](v: var T; mask: T) {.inline.} =
-    ## Mutates ``v``, with all the ``1`` bits from ``mask`` set to 0.
+    ## Mutates `v`, with all the `1` bits from `mask` set to 0.
     ##
-    ## Effectively maps to a `bitand` operation with an *inverted mask.*
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
+    ## with an *inverted mask*.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.clearMask(0b0000_1010'u8)
@@ -249,9 +252,10 @@ when defined(nimHasalignOf):
     v = bitand(v, bitnot(mask))
 
   proc clearMask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
-    ## Mutates ``v``, with all the ``1`` bits in the range of ``slice`` set to 0.
+    ## Mutates `v`, with all the `1` bits in the range of `slice` set to 0.
     ##
-    ## Effectively maps to a `bitand` operation with an *inverted mask.*
+    ## Effectively maps to a `bitand <#bitand.m,T,T,varargs[T]>`_ operation
+    ## with an *inverted mask*.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.clearMask(1 .. 3)
@@ -260,29 +264,29 @@ when defined(nimHasalignOf):
     v = bitand(v, bitnot(toMask[T](slice)))
 
   func flipMasked*[T: SomeInteger](v, mask :T): T {.inline, since: (1, 3).} =
-    ## Returns ``v``, with all the ``1`` bits from ``mask`` flipped.
+    ## Returns `v`, with all the `1` bits from `mask` flipped.
     ##
-    ## Effectively maps to a `bitxor` operation.
+    ## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
-      var v = 0b0000_0011'u8
+      let v = 0b0000_0011'u8
       doAssert v.flipMasked(0b0000_1010'u8) == 0b0000_1001'u8
 
     bitxor(v, mask)
 
   func flipMasked*[T: SomeInteger](v: T; slice: Slice[int]): T {.inline, since: (1, 3).} =
-    ## Returns ``v``, with all the ``1`` bits in the range of ``slice`` flipped.
+    ## Returns `v`, with all the `1` bits in the range of `slice` flipped.
     ##
-    ## Effectively maps to a `bitxor` operation.
+    ## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
-      var v = 0b0000_0011'u8
+      let v = 0b0000_0011'u8
       doAssert v.flipMasked(1 .. 3) == 0b0000_1101'u8
 
     bitxor(v, toMask[T](slice))
 
   proc flipMask*[T: SomeInteger](v: var T; mask: T) {.inline.} =
-    ## Mutates ``v``, with all the ``1`` bits from ``mask`` flipped.
+    ## Mutates `v`, with all the `1` bits from `mask` flipped.
     ##
-    ## Effectively maps to a `bitxor` operation.
+    ## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.flipMask(0b0000_1010'u8)
@@ -291,9 +295,9 @@ when defined(nimHasalignOf):
     v = bitxor(v, mask)
 
   proc flipMask*[T: SomeInteger](v: var T; slice: Slice[int]) {.inline, since: (1, 3).} =
-    ## Mutates ``v``, with all the ``1`` bits in the range of ``slice`` flipped.
+    ## Mutates `v`, with all the `1` bits in the range of `slice` flipped.
     ##
-    ## Effectively maps to a `bitxor` operation.
+    ## Effectively maps to a `bitxor <#bitxor.m,T,T,varargs[T]>`_ operation.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.flipMask(1 .. 3)
@@ -302,7 +306,7 @@ when defined(nimHasalignOf):
     v = bitxor(v, toMask[T](slice))
 
   proc setBit*[T: SomeInteger](v: var T; bit: BitsRange[T]) {.inline.} =
-    ## Mutates ``v``, with the bit at position ``bit`` set to 1
+    ## Mutates `v`, with the bit at position `bit` set to 1.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.setBit(5'u8)
@@ -311,7 +315,7 @@ when defined(nimHasalignOf):
     v.setMask(1.T shl bit)
 
   proc clearBit*[T: SomeInteger](v: var T; bit: BitsRange[T]) {.inline.} =
-    ## Mutates ``v``, with the bit at position ``bit`` set to 0
+    ## Mutates `v`, with the bit at position `bit` set to 0.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.clearBit(1'u8)
@@ -320,7 +324,7 @@ when defined(nimHasalignOf):
     v.clearMask(1.T shl bit)
 
   proc flipBit*[T: SomeInteger](v: var T; bit: BitsRange[T]) {.inline.} =
-    ## Mutates ``v``, with the bit at position ``bit`` flipped
+    ## Mutates `v`, with the bit at position `bit` flipped.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.flipBit(1'u8)
@@ -333,7 +337,7 @@ when defined(nimHasalignOf):
     v.flipMask(1.T shl bit)
 
   macro setBits*(v: typed; bits: varargs[typed]): untyped =
-    ## Mutates ``v``, with the bits at positions ``bits`` set to 1
+    ## Mutates `v`, with the bits at positions `bits` set to 1.
     runnableExamples:
       var v = 0b0000_0011'u8
       v.setBits(3, 5, 7)
@@ -345,7 +349,7 @@ when defined(nimHasalignOf):
       result.add newCall("setBit", v, bit)
 
   macro clearBits*(v: typed; bits: varargs[typed]): untyped =
-    ## Mutates ``v``, with the bits at positions ``bits`` set to 0
+    ## Mutates `v`, with the bits at positions `bits` set to 0.
     runnableExamples:
       var v = 0b1111_1111'u8
       v.clearBits(1, 3, 5, 7)
@@ -357,7 +361,7 @@ when defined(nimHasalignOf):
       result.add newCall("clearBit", v, bit)
 
   macro flipBits*(v: typed; bits: varargs[typed]): untyped =
-    ## Mutates ``v``, with the bits at positions ``bits`` set to 0
+    ## Mutates `v`, with the bits at positions `bits` set to 0.
     runnableExamples:
       var v = 0b0000_1111'u8
       v.flipBits(1, 3, 5, 7)
@@ -370,9 +374,9 @@ when defined(nimHasalignOf):
 
 
   proc testBit*[T: SomeInteger](v: T; bit: BitsRange[T]): bool {.inline.} =
-    ## Returns true if the bit in ``v`` at positions ``bit`` is set to 1
+    ## Returns true if the bit in `v` at positions `bit` is set to 1.
     runnableExamples:
-      var v = 0b0000_1111'u8
+      let v = 0b0000_1111'u8
       doAssert v.testBit(0)
       doAssert not v.testBit(7)
 
@@ -381,19 +385,19 @@ when defined(nimHasalignOf):
 
 # #### Pure Nim version ####
 
-proc firstSetBitNim(x: uint32): int {.inline, noSideEffect.} =
+func firstSetBitNim(x: uint32): int {.inline.} =
   ## Returns the 1-based index of the least significant set bit of x, or if x is zero, returns zero.
   # https://graphics.stanford.edu/%7Eseander/bithacks.html#ZerosOnRightMultLookup
   const lookup: array[32, uint8] = [0'u8, 1, 28, 2, 29, 14, 24, 3, 30, 22, 20, 15,
     25, 17, 4, 8, 31, 27, 13, 23, 21, 19, 16, 7, 26, 12, 18, 6, 11, 5, 10, 9]
-  var v = x.uint32
-  var k = not v + 1 # get two's complement # cast[uint32](-cast[int32](v))
+  let v = x.uint32
+  let k = not v + 1 # get two's complement # cast[uint32](-cast[int32](v))
   result = 1 + lookup[uint32((v and k) * 0x077CB531'u32) shr 27].int
 
-proc firstSetBitNim(x: uint64): int {.inline, noSideEffect.} =
+func firstSetBitNim(x: uint64): int {.inline.} =
   ## Returns the 1-based index of the least significant set bit of x, or if x is zero, returns zero.
   # https://graphics.stanford.edu/%7Eseander/bithacks.html#ZerosOnRightMultLookup
-  var v = uint64(x)
+  let v = uint64(x)
   var k = uint32(v and 0xFFFFFFFF'u32)
   if k == 0:
     k = uint32(v shr 32'u32) and 0xFFFFFFFF'u32
@@ -402,7 +406,7 @@ proc firstSetBitNim(x: uint64): int {.inline, noSideEffect.} =
     result = 0
   result += firstSetBitNim(k)
 
-proc fastlog2Nim(x: uint32): int {.inline, noSideEffect.} =
+func fastlog2Nim(x: uint32): int {.inline.} =
   ## Quickly find the log base 2 of a 32-bit or less integer.
   # https://graphics.stanford.edu/%7Eseander/bithacks.html#IntegerLogDeBruijn
   # https://stackoverflow.com/questions/11376288/fast-computing-of-log2-for-64-bit-integers
@@ -416,7 +420,7 @@ proc fastlog2Nim(x: uint32): int {.inline, noSideEffect.} =
   v = v or v shr 16
   result = lookup[uint32(v * 0x07C4ACDD'u32) shr 27].int
 
-proc fastlog2Nim(x: uint64): int {.inline, noSideEffect.} =
+func fastlog2Nim(x: uint64): int {.inline.} =
   ## Quickly find the log base 2 of a 64-bit integer.
   # https://graphics.stanford.edu/%7Eseander/bithacks.html#IntegerLogDeBruijn
   # https://stackoverflow.com/questions/11376288/fast-computing-of-log2-for-64-bit-integers
@@ -479,24 +483,24 @@ when useGCC_builtins:
 
 elif useVCC_builtins:
   # Counts the number of one bits (population count) in a 16-, 32-, or 64-byte unsigned integer.
-  proc builtin_popcnt16(a2: uint16): uint16 {.
-      importc: "__popcnt16", header: "<intrin.h>", noSideEffect.}
-  proc builtin_popcnt32(a2: uint32): uint32 {.
-      importc: "__popcnt", header: "<intrin.h>", noSideEffect.}
-  proc builtin_popcnt64(a2: uint64): uint64 {.
-      importc: "__popcnt64", header: "<intrin.h>", noSideEffect.}
+  func builtin_popcnt16(a2: uint16): uint16 {.
+      importc: "__popcnt16", header: "<intrin.h>".}
+  func builtin_popcnt32(a2: uint32): uint32 {.
+      importc: "__popcnt", header: "<intrin.h>".}
+  func builtin_popcnt64(a2: uint64): uint64 {.
+      importc: "__popcnt64", header: "<intrin.h>".}
 
   # Search the mask data from most significant bit (MSB) to least significant bit (LSB) for a set bit (1).
-  proc bitScanReverse(index: ptr culong, mask: culong): cuchar {.
-      importc: "_BitScanReverse", header: "<intrin.h>", noSideEffect.}
-  proc bitScanReverse64(index: ptr culong, mask: uint64): cuchar {.
-      importc: "_BitScanReverse64", header: "<intrin.h>", noSideEffect.}
+  func bitScanReverse(index: ptr culong, mask: culong): cuchar {.
+      importc: "_BitScanReverse", header: "<intrin.h>".}
+  func bitScanReverse64(index: ptr culong, mask: uint64): cuchar {.
+      importc: "_BitScanReverse64", header: "<intrin.h>".}
 
   # Search the mask data from least significant bit (LSB) to the most significant bit (MSB) for a set bit (1).
-  proc bitScanForward(index: ptr culong, mask: culong): cuchar {.
-      importc: "_BitScanForward", header: "<intrin.h>", noSideEffect.}
-  proc bitScanForward64(index: ptr culong, mask: uint64): cuchar {.
-      importc: "_BitScanForward64", header: "<intrin.h>", noSideEffect.}
+  func bitScanForward(index: ptr culong, mask: culong): cuchar {.
+      importc: "_BitScanForward", header: "<intrin.h>".}
+  func bitScanForward64(index: ptr culong, mask: uint64): cuchar {.
+      importc: "_BitScanForward64", header: "<intrin.h>".}
 
   template vcc_scan_impl(fnc: untyped; v: untyped): int =
     var index: culong
@@ -508,22 +512,22 @@ elif useICC_builtins:
   # Intel compiler intrinsics: http://fulla.fnal.gov/intel/compiler_c/main_cls/intref_cls/common/intref_allia_misc.htm
   # see also: https://software.intel.com/en-us/node/523362
   # Count the number of bits set to 1 in an integer a, and return that count in dst.
-  proc builtin_popcnt32(a: cint): cint {.
-      importc: "_popcnt", header: "<immintrin.h>", noSideEffect.}
-  proc builtin_popcnt64(a: uint64): cint {.
-      importc: "_popcnt64", header: "<immintrin.h>", noSideEffect.}
+  func builtin_popcnt32(a: cint): cint {.
+      importc: "_popcnt", header: "<immintrin.h>".}
+  func builtin_popcnt64(a: uint64): cint {.
+      importc: "_popcnt64", header: "<immintrin.h>".}
 
   # Returns the number of trailing 0-bits in x, starting at the least significant bit position. If x is 0, the result is undefined.
-  proc bitScanForward(p: ptr uint32, b: uint32): cuchar {.
-      importc: "_BitScanForward", header: "<immintrin.h>", noSideEffect.}
-  proc bitScanForward64(p: ptr uint32, b: uint64): cuchar {.
-      importc: "_BitScanForward64", header: "<immintrin.h>", noSideEffect.}
+  func bitScanForward(p: ptr uint32, b: uint32): cuchar {.
+      importc: "_BitScanForward", header: "<immintrin.h>".}
+  func bitScanForward64(p: ptr uint32, b: uint64): cuchar {.
+      importc: "_BitScanForward64", header: "<immintrin.h>".}
 
   # Returns the number of leading 0-bits in x, starting at the most significant bit position. If x is 0, the result is undefined.
-  proc bitScanReverse(p: ptr uint32, b: uint32): cuchar {.
-      importc: "_BitScanReverse", header: "<immintrin.h>", noSideEffect.}
-  proc bitScanReverse64(p: ptr uint32, b: uint64): cuchar {.
-      importc: "_BitScanReverse64", header: "<immintrin.h>", noSideEffect.}
+  func bitScanReverse(p: ptr uint32, b: uint32): cuchar {.
+      importc: "_BitScanReverse", header: "<immintrin.h>".}
+  func bitScanReverse64(p: ptr uint32, b: uint64): cuchar {.
+      importc: "_BitScanReverse64", header: "<immintrin.h>".}
 
   template icc_scan_impl(fnc: untyped; v: untyped): int =
     var index: uint32
@@ -531,8 +535,8 @@ elif useICC_builtins:
     index.int
 
 
-proc countSetBits*(x: SomeInteger): int {.inline, noSideEffect.} =
-  ## Counts the set bits in integer. (also called `Hamming weight`:idx:.)
+func countSetBits*(x: SomeInteger): int {.inline.} =
+  ## Counts the set bits in an integer (also called `Hamming weight`:idx:).
   runnableExamples:
     doAssert countSetBits(0b0000_0011'u8) == 2
     doAssert countSetBits(0b1010_1010'u8) == 4
@@ -562,13 +566,13 @@ proc countSetBits*(x: SomeInteger): int {.inline, noSideEffect.} =
       when sizeof(x) <= 4: result = countSetBitsNim(x.uint32)
       else: result = countSetBitsNim(x.uint64)
 
-proc popcount*(x: SomeInteger): int {.inline, noSideEffect.} =
-  ## Alias for for `countSetBits <#countSetBits,SomeInteger>`_. (Hamming weight.)
+func popcount*(x: SomeInteger): int {.inline.} =
+  ## Alias for `countSetBits <#countSetBits,SomeInteger>`_ (Hamming weight).
   result = countSetBits(x)
 
-proc parityBits*(x: SomeInteger): int {.inline, noSideEffect.} =
-  ## Calculate the bit parity in integer. If number of 1-bit
-  ## is odd parity is 1, otherwise 0.
+func parityBits*(x: SomeInteger): int {.inline.} =
+  ## Calculate the bit parity in an integer. If the number of 1-bits
+  ## is odd, the parity is 1, otherwise 0.
   runnableExamples:
     doAssert parityBits(0b0000_0000'u8) == 0
     doAssert parityBits(0b0101_0001'u8) == 1
@@ -589,10 +593,10 @@ proc parityBits*(x: SomeInteger): int {.inline, noSideEffect.} =
       when sizeof(x) <= 4: result = parityImpl(x.uint32)
       else: result = parityImpl(x.uint64)
 
-proc firstSetBit*(x: SomeInteger): int {.inline, noSideEffect.} =
-  ## Returns the 1-based index of the least significant set bit of x.
-  ## If `x` is zero, when ``noUndefinedBitOpts`` is set, result is 0,
-  ## otherwise result is undefined.
+func firstSetBit*(x: SomeInteger): int {.inline.} =
+  ## Returns the 1-based index of the least significant set bit of `x`.
+  ## If `x` is zero, when `noUndefinedBitOpts` is set, the result is 0,
+  ## otherwise the result is undefined.
   runnableExamples:
     doAssert firstSetBit(0b0000_0001'u8) == 1
     doAssert firstSetBit(0b0000_0010'u8) == 2
@@ -633,10 +637,10 @@ proc firstSetBit*(x: SomeInteger): int {.inline, noSideEffect.} =
       when sizeof(x) <= 4: result = firstSetBitNim(x.uint32)
       else: result = firstSetBitNim(x.uint64)
 
-proc fastLog2*(x: SomeInteger): int {.inline, noSideEffect.} =
+func fastLog2*(x: SomeInteger): int {.inline.} =
   ## Quickly find the log base 2 of an integer.
-  ## If `x` is zero, when ``noUndefinedBitOpts`` is set, result is -1,
-  ## otherwise result is undefined.
+  ## If `x` is zero, when `noUndefinedBitOpts` is set, the result is -1,
+  ## otherwise the result is undefined.
   runnableExamples:
     doAssert fastLog2(0b0000_0001'u8) == 0
     doAssert fastLog2(0b0000_0010'u8) == 1
@@ -673,12 +677,12 @@ proc fastLog2*(x: SomeInteger): int {.inline, noSideEffect.} =
       when sizeof(x) <= 4: result = fastlog2Nim(x.uint32)
       else: result = fastlog2Nim(x.uint64)
 
-proc countLeadingZeroBits*(x: SomeInteger): int {.inline, noSideEffect.} =
-  ## Returns the number of leading zero bits in integer.
-  ## If `x` is zero, when ``noUndefinedBitOpts`` is set, result is 0,
-  ## otherwise result is undefined.
+func countLeadingZeroBits*(x: SomeInteger): int {.inline.} =
+  ## Returns the number of leading zero bits in an integer.
+  ## If `x` is zero, when `noUndefinedBitOpts` is set, the result is 0,
+  ## otherwise the result is undefined.
   ##
-  ## See also:
+  ## **See also:**
   ## * `countTrailingZeroBits proc <#countTrailingZeroBits,SomeInteger>`_
   runnableExamples:
     doAssert countLeadingZeroBits(0b0000_0001'u8) == 7
@@ -702,12 +706,12 @@ proc countLeadingZeroBits*(x: SomeInteger): int {.inline, noSideEffect.} =
       when sizeof(x) <= 4: result = sizeof(x)*8 - 1 - fastlog2Nim(x.uint32)
       else: result = sizeof(x)*8 - 1 - fastlog2Nim(x.uint64)
 
-proc countTrailingZeroBits*(x: SomeInteger): int {.inline, noSideEffect.} =
-  ## Returns the number of trailing zeros in integer.
-  ## If `x` is zero, when ``noUndefinedBitOpts`` is set, result is 0,
-  ## otherwise result is undefined.
+func countTrailingZeroBits*(x: SomeInteger): int {.inline.} =
+  ## Returns the number of trailing zeros in an integer.
+  ## If `x` is zero, when `noUndefinedBitOpts` is set, the result is 0,
+  ## otherwise the result is undefined.
   ##
-  ## See also:
+  ## **See also:**
   ## * `countLeadingZeroBits proc <#countLeadingZeroBits,SomeInteger>`_
   runnableExamples:
     doAssert countTrailingZeroBits(0b0000_0001'u8) == 0
@@ -769,7 +773,7 @@ when useBuiltinsRotate:
     when defined(amd64):
       func builtin_rotl64(value: culonglong, shift: culonglong): culonglong
                          {.importc: "__builtin_rotateleft64", nodecl.}
-    
+
     func builtin_rotr8(value: cuchar, shift: cuchar): cuchar
                       {.importc: "__builtin_rotateright8", nodecl.}
     func builtin_rotr16(value: cushort, shift: cushort): cushort
@@ -863,7 +867,7 @@ func rotateLeftBits*(value: uint8, shift: range[0..8]): uint8 {.inline.} =
   ## Left-rotate bits in a 8-bits value.
   runnableExamples:
     doAssert rotateLeftBits(0b0110_1001'u8, 4) == 0b1001_0110'u8
-  
+
   when nimvm:
     rotl(value, shift.int32)
   else:
@@ -891,7 +895,7 @@ func rotateLeftBits*(value: uint32, shift: range[0..32]): uint32 {.inline.} =
   runnableExamples:
     doAssert rotateLeftBits(0b0000111111110000_1111000000001111'u32, 16) ==
       0b1111000000001111_0000111111110000'u32
-  
+
   when nimvm:
     rotl(value, shift.int32)
   else:
@@ -969,15 +973,14 @@ func rotateRightBits*(value: uint64, shift: range[0..64]): uint64 {.inline.} =
     else:
       rotr(value, shift.int32)
 
-proc repeatBits[T: SomeUnsignedInt](x: SomeUnsignedInt; retType: type[T]): T {.
-  noSideEffect.} =
+func repeatBits[T: SomeUnsignedInt](x: SomeUnsignedInt; retType: type[T]): T  =
   result = x
   var i = 1
   while i != (sizeof(T) div sizeof(x)):
     result = (result shl (sizeof(x)*8*i)) or result
     i *= 2
 
-proc reverseBits*[T: SomeUnsignedInt](x: T): T {.noSideEffect.} =
+func reverseBits*[T: SomeUnsignedInt](x: T): T =
   ## Return the bit reversal of x.
   runnableExamples:
     doAssert reverseBits(0b10100100'u8) == 0b00100101'u8