chore(stdlib): Add examples to Int8 module (#1958)

Author: spotandjake

stdlib/int8.gr

@@ -2,6 +2,9 @@
  * Utilities for working with the Int8 type.
  * @example include "int8"
  *
+ * @example 1s
+ * @example -1s
+ *
  * @since v0.6.0
  */
 
@@ -51,6 +54,8 @@ provide { fromNumber, toNumber }
  * @param number: The value to convert
  * @returns The Uint8 represented as an Int8
  *
+ * @example Int8.fromUint8(1us) == 1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -67,6 +72,9 @@ provide let fromUint8 = (x: Uint8) => {
  * @param value: The value to increment
  * @returns The incremented value
  *
+ * @example Int8.incr(1s) == 2s
+ * @example Int8.incr(-2s) == -1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -83,6 +91,9 @@ provide let incr = (value: Int8) => {
  * @param value: The value to decrement
  * @returns The decremented value
  *
+ * @example Int8.decr(2s) == 1s
+ * @example Int8.decr(0s) == -1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -100,6 +111,10 @@ provide let decr = (value: Int8) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * from Int8 use { (+) }
+ * assert 1s + 1s == 2s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -121,6 +136,10 @@ provide let (+) = (x: Int8, y: Int8) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * from Int8 use { (-) }
+ * assert 2s - 1s == 1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -139,6 +158,10 @@ provide let (-) = (x: Int8, y: Int8) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * from Int8 use { (*) }
+ * assert 2s * 2s == 4s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -156,6 +179,10 @@ provide let (*) = (x: Int8, y: Int8) => {
  * @param y: The second operand
  * @returns The quotient of its operands
  *
+ * @example
+ * from Int8 use { (/) }
+ * assert 8s / 2s == 4s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -174,6 +201,8 @@ provide let (/) = (x: Int8, y: Int8) => {
  * @param y: The second operand
  * @returns The remainder of its operands
  *
+ * @example Int8.rem(8s, 3s) == 2s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -202,6 +231,10 @@ let abs = n => {
  *
  * @throws ModuloByZero: When `y` is zero
  *
+ * @example
+ * from Int8 use { (%) }
+ * assert -5s % 3s == 1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -233,6 +266,10 @@ provide let (%) = (x: Int8, y: Int8) => {
  * @param amount: The number of bits to shift by
  * @returns The shifted value
  *
+ * @example
+ * from Int8 use { (<<) }
+ * assert (5s << 1s) == 10s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -252,6 +289,10 @@ provide let (<<) = (value: Int8, amount: Int8) => {
  * @param amount: The amount to shift by
  * @returns The shifted value
  *
+ * @example
+ * from Int8 use { (>>) }
+ * assert (5s >> 1s) == 2s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -271,6 +312,10 @@ provide let (>>) = (value: Int8, amount: Int8) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * from Int8 use { (==) }
+ * assert 1s == 1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -287,6 +332,10 @@ provide let (==) = (x: Int8, y: Int8) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * from Int8 use { (!=) }
+ * assert 1s != 2s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -303,6 +352,10 @@ provide let (!=) = (x: Int8, y: Int8) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * from Int8 use { (<) }
+ * assert 1s < 2s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -319,6 +372,10 @@ provide let (<) = (x: Int8, y: Int8) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * from Int8 use { (>) }
+ * assert 2s > 1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -335,6 +392,13 @@ provide let (>) = (x: Int8, y: Int8) => {
  * @param y: The second value
  * @returns `true` if the first value is less than or equal to the second value or `false` otherwise
  *
+ * @example
+ * from Int8 use { (<=) }
+ * assert 1s <= 2s
+ * @example
+ * from Int8 use { (<=) }
+ * assert 1s <= 1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -351,6 +415,13 @@ provide let (<=) = (x: Int8, y: Int8) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than or equal to the second value or `false` otherwise
  *
+ * @example
+ * from Int8 use { (>=) }
+ * assert 2s >= 1s
+ * @example
+ * from Int8 use { (>=) }
+ * assert 1s >= 1s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -366,6 +437,8 @@ provide let (>=) = (x: Int8, y: Int8) => {
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example Int.lnot(-5s) == 4s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -381,6 +454,10 @@ provide let lnot = (value: Int8) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of both operands are `1`
  *
+ * @example
+ * from Int8 use { (&) }
+ * assert (3s & 4s) == 0s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -399,6 +476,10 @@ provide let (&) = (x: Int8, y: Int8) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either or both operands are `1`
  *
+ * @example
+ * from Int8 use { (|) }
+ * assert (3s | 4s) == 7s
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -417,6 +498,10 @@ provide let (|) = (x: Int8, y: Int8) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of either but not both operands are `1`
  *
+ * @example
+ * from Int8 use { (^) }
+ * assert (3s ^ 5s) == 6s
+ *
  * @since v0.6.0
  */
 @unsafe