chore(stdlib): Add examples to Uint8 docs (#2133)

grain-lang · Aug 4, 2024 · 9af3fc8 · 9af3fc8
1 parent 1ad351c
commit 9af3fc8
Show file tree

Hide file tree

Showing 2 changed files with 242 additions and 0 deletions.
diff --git a/stdlib/uint8.gr b/stdlib/uint8.gr
@@ -2,6 +2,9 @@
  * Utilities for working with the Uint8 type.
  * @example from "uint8" include Uint8
  *
+ * @example 1us
+ * @example 10us
+ *
  * @since v0.6.0
  */
 module Uint8
@@ -33,6 +36,9 @@ provide { fromNumber, toNumber }
  * @param number: The value to convert
  * @returns The Int8 represented as a Uint8
  *
+ * @example Uint8.fromInt8(1s) == 1us
+ * @example Uint8.fromInt8(-1s) == 255us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -49,6 +55,8 @@ provide let fromInt8 = (number: Int8) => {
  * @param value: The value to increment
  * @returns The incremented value
  *
+ * @example Uint8.incr(1us) == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -65,6 +73,9 @@ provide let incr = (value: Uint8) => {
  * @param value: The value to decrement
  * @returns The decremented value
  *
+ * @example Uint8.decr(1us) == 0us
+ * @example Uint8.decr(0us) == 255us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -82,6 +93,10 @@ provide let decr = (value: Uint8) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * use Uint8.{ (+) }
+ * assert 1us + 1us == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -103,6 +118,10 @@ provide let (+) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * use Uint8.{ (-) }
+ * assert 2us - 1us == 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -121,6 +140,10 @@ provide let (-) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * use Uint8.{ (*) }
+ * assert 2us * 2us == 4us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -138,6 +161,10 @@ provide let (*) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The quotient of its operands
  *
+ * @example
+ * use Uint8.{ (/) }
+ * assert 5us / 2us == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -155,6 +182,8 @@ provide let (/) = (x: Uint8, y: Uint8) => {
  * @param y: The second operand
  * @returns The remainder of its operands
  *
+ * @example Uint8.rem(5us, 2us) == 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -172,6 +201,10 @@ provide let rem = (x: Uint8, y: Uint8) => {
  * @param amount: The number of bits to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Uint8.{ (<<) }
+ * assert (5us << 1us) == 10us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -191,6 +224,10 @@ provide let (<<) = (value: Uint8, amount: Uint8) => {
  * @param amount: The amount to shift by
  * @returns The shifted value
  *
+ * @example
+ * use Uint8.{ (>>>) }
+ * assert (5us >>> 1us) == 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -210,6 +247,10 @@ provide let (>>>) = (value: Uint8, amount: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (==) }
+ * assert 1us == 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -226,6 +267,10 @@ provide let (==) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (!=) }
+ * assert 1us != 3us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -242,6 +287,10 @@ provide let (!=) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (<) }
+ * assert 1us < 5us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -258,6 +307,10 @@ provide let (<) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (>) }
+ * assert 4us > 2us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -274,6 +327,13 @@ provide let (>) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is less than or equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (<=) }
+ * assert 1us <= 2us
+ * @example
+ * use Uint8.{ (<=) }
+ * assert 1us <= 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -290,6 +350,13 @@ provide let (<=) = (x: Uint8, y: Uint8) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than or equal to the second value or `false` otherwise
  *
+ * @example
+ * use Uint8.{ (>=) }
+ * assert 3us >= 2us
+ * @example
+ * use Uint8.{ (>=) }
+ * assert 1us >= 1us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -305,6 +372,8 @@ provide let (>=) = (x: Uint8, y: Uint8) => {
  * @param value: The given value
  * @returns Containing the inverted bits of the given value
  *
+ * @example Uint8.lnot(5us) == 250us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -320,6 +389,10 @@ provide let lnot = (value: Uint8) => {
  * @param y: The second operand
  * @returns Containing a `1` in each bit position for which the corresponding bits of both operands are `1`
  *
+ * @example
+ * use Uint8.{ (&) }
+ * assert (3us & 4us) == 0us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -338,6 +411,10 @@ provide let (&) = (x: Uint8, y: Uint8) => {
  * @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
+ * use Uint8.{ (|) }
+ * assert (3us | 4us) == 7us
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -356,6 +433,10 @@ provide let (|) = (x: Uint8, y: Uint8) => {
  * @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
+ * use Uint8.{ (^) }
+ * assert (3us ^ 5us) == 6us
+ *
  * @since v0.6.0
  */
 @unsafe