chore(stdlib): Add examples to Uint16 docs (#2135)

grain-lang · Aug 5, 2024 · a4d9c61 · a4d9c61
1 parent 6c8d1b0
commit a4d9c61
Show file tree

Hide file tree

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