Fix doc of toInt/toUint + add more docs about undefined behaviours

stint/io.nim

@@ -74,22 +74,24 @@ func to*(x: SomeUnsignedInt, T: typedesc[StUint]): T =
   stuint(x, result.bits)
 
 func toInt*(num: Stint or StUint): int {.inline.}=
-  # Returns as int. Result is modulo 2^(sizeof(int)
+  # Returns as int.
+  # Result is undefined if input does not fit in an int64
   cast[int](num.data.least_significant_word)
 
 func toUint*(num: Stint or StUint): uint {.inline.}=
-  # Returns as int. Result is modulo 2^(sizeof(int)
+  # Returns as uint. Result is modulo 2^(sizeof(uint))
   num.data.least_significant_word
 
 func toInt64*(num: Stint or StUint): int64 {.inline.}=
-  # Returns as int64. Result is modulo 2^(sizeof(int)
+  # Returns as int64.
+  # Result is undefined if input does not fit in an int64
   when sizeof(uint) == 8:
     cast[int64](num.data.least_significant_word)
   else:
     cast[int64](num.data.least_significant_two_words)
 
 func toUint64*(num: Stint or StUint): uint64 {.inline.}=
-  # Returns as int. Result is modulo 2^(sizeof(int)
+  # Returns as uint64. Result is modulo 2^64.
   when sizeof(uint) == 8:
     num.data.least_significant_word.uint64
   else:

stint/private/uint_bitwise_ops.nim

@@ -59,6 +59,8 @@ func `shl`*(x: UintImpl, y: SomeInteger): UintImpl {.inline.}=
 
 func `shr`*(x: UintImpl, y: SomeInteger): UintImpl {.inline.}=
   ## Compute the `shift right` operation of x and y
+  ## Similar to C standard, result is undefined if y is bigger
+  ## than the number of bits in x.
   const halfSize: type(y) = getSize(x) div 2
 
   if y == 0:

stint/uint_public.nim

@@ -104,6 +104,8 @@ func `shr`*(x: StUint, y: SomeInteger): StUint {.inline.} =
   result.data = x.data shr y
 func `shl`*(x: StUint, y: SomeInteger): StUint {.inline.} =
   ## Logical shift right
+  ## Similar to C standard, result is undefined if y is bigger
+  ## than the number of bits in x.
   result.data = x.data shl y
 
 import ./private/uint_highlow