chore(stdlib): Add Examples to rational docs

stdlib/rational.gr

@@ -2,6 +2,9 @@
  * Utilities for working with the Rational type.
  * @example include "rational"
  *
+ * @example 1/2r
+ * @example 3/4r
+ *
  * @since v0.6.0
  */
 
@@ -30,6 +33,9 @@ provide { fromNumber, toNumber, numerator, denominator }
  * @param x: The rational to split
  * @returns The numerator and denominator of the rational
  *
+ * @example Rational.toIntegerRatio(1/2r) == (1, 2)
+ * @example Rational.toIntegerRation(2/8r) == (1, 4)
+ *
  * @since v0.6.0
  */
 provide let toIntegerRatio = x => {
@@ -46,6 +52,9 @@ provide let toIntegerRatio = x => {
  * @throws InvalidArgument(String): If the numerator is not an integer
  * @throws InvalidArgument(String): If the denominator is not an integer
  *
+ * @example Rational.fromIntegerRatio(1, 2) == 1/2r
+ * @example Rational.fromIntegerRatio(2, 8) == 1/4r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -68,6 +77,10 @@ provide let fromIntegerRatio = (numerator: Number, denominator: Number) => {
  * @param y: The second operand
  * @returns The sum of the two operands
  *
+ * @example
+ * from Rational use { (+) }
+ * assert 1/2r + 1/4r == 3/4r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -85,6 +98,10 @@ provide let (+) = (x: Rational, y: Rational) => {
  * @param y: The second operand
  * @returns The difference of the two operands
  *
+ * @example
+ * from Rational use { (-) }
+ * assert 1/2r - 1/4r == 1/4r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -102,6 +119,10 @@ provide let (-) = (x: Rational, y: Rational) => {
  * @param y: The second operand
  * @returns The product of the two operands
  *
+ * @example
+ * from Rational use { (*) }
+ * assert 1/2r * 1/4r == 1/8r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -119,6 +140,10 @@ provide let (*) = (x: Rational, y: Rational) => {
  * @param y: The second operand
  * @returns The quotient of the two operands
  *
+ * @example
+ * from Rational use { (/) }
+ * assert 1/2r / 1/4r == 2/1r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -136,6 +161,10 @@ provide let (/) = (x: Rational, y: Rational) => {
  * @param y: The second value
  * @returns `true` if the first value is equal to the second value or `false` otherwise
  *
+ * @example
+ * from Rational use { (==) }
+ * assert 1/2r == 1/2r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -152,6 +181,10 @@ provide let (==) = (x: Rational, y: Rational) => {
  * @param y: The second value
  * @returns `true` if the first value is not equal to the second value or `false` otherwise
  *
+ * @example
+ * from Rational use { (!=) }
+ * assert 1/2r != 1/4r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -168,6 +201,10 @@ provide let (!=) = (x: Rational, y: Rational) => {
  * @param y: The second value
  * @returns `true` if the first value is less than the second value or `false` otherwise
  *
+ * @example
+ * from Rational use { (<) }
+ * assert 1/4r < 1/2r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -185,6 +222,10 @@ provide let (<) = (x: Rational, y: Rational) => {
  * @param y: The second value
  * @returns `true` if the first value is greater than the second value or `false` otherwise
  *
+ * @example
+ * from Rational use { (>) }
+ * assert 1/2r > 1/4r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -202,6 +243,13 @@ provide let (>) = (x: Rational, y: Rational) => {
  * @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 Rational use { (<=) }
+ * assert 1/4r <= 1/2r
+ * @example
+ * from Rational use { (<=) }
+ * assert 1/2r <= 1/2r
+ *
  * @since v0.6.0
  */
 @unsafe
@@ -219,6 +267,13 @@ provide let (<=) = (x: Rational, y: Rational) => {
  * @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 Rational use { (>=) }
+ * assert 1/2r >= 1/4r
+ * @example
+ * from Rational use { (>=) }
+ * assert 1/2r >= 1/2r
+ *
  * @since v0.6.0
  */
 @unsafe

stdlib/rational.md

@@ -13,6 +13,14 @@ No other changes yet.
 include "rational"
 ```
 
+```grain
+1/2r
+```
+
+```grain
+3/4r
+```
+
 ## Values
 
 Functions and constants included in the Rational module.
@@ -142,6 +150,16 @@ Returns:
 |----|-----------|
 |`(Number, Number)`|The numerator and denominator of the rational|
 
+Examples:
+
+```grain
+Rational.toIntegerRatio(1/2r) == (1, 2)
+```
+
+```grain
+Rational.toIntegerRation(2/8r) == (1, 4)
+```
+
 ### Rational.**fromIntegerRatio**
 
 <details disabled>
@@ -175,6 +193,16 @@ Throws:
 * If the numerator is not an integer
 * If the denominator is not an integer
 
+Examples:
+
+```grain
+Rational.fromIntegerRatio(1, 2) == 1/2r
+```
+
+```grain
+Rational.fromIntegerRatio(2, 8) == 1/4r
+```
+
 ### Rational.**(+)**
 
 <details disabled>
@@ -201,6 +229,13 @@ Returns:
 |----|-----------|
 |`Rational`|The sum of the two operands|
 
+Examples:
+
+```grain
+from Rational use { (+) }
+assert 1/2r + 1/4r == 3/4r
+```
+
 ### Rational.**(-)**
 
 <details disabled>
@@ -227,6 +262,13 @@ Returns:
 |----|-----------|
 |`Rational`|The difference of the two operands|
 
+Examples:
+
+```grain
+from Rational use { (-) }
+assert 1/2r - 1/4r == 1/4r
+```
+
 ### Rational.**(*)**
 
 <details disabled>
@@ -253,6 +295,13 @@ Returns:
 |----|-----------|
 |`Rational`|The product of the two operands|
 
+Examples:
+
+```grain
+from Rational use { (*) }
+assert 1/2r * 1/4r == 1/8r
+```
+
 ### Rational.**(/)**
 
 <details disabled>
@@ -279,6 +328,13 @@ Returns:
 |----|-----------|
 |`Rational`|The quotient of the two operands|
 
+Examples:
+
+```grain
+from Rational use { (/) }
+assert 1/2r / 1/4r == 2/1r
+```
+
 ### Rational.**(==)**
 
 <details disabled>
@@ -305,6 +361,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from Rational use { (==) }
+assert 1/2r == 1/2r
+```
+
 ### Rational.**(!=)**
 
 <details disabled>
@@ -331,6 +394,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is not equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from Rational use { (!=) }
+assert 1/2r != 1/4r
+```
+
 ### Rational.**(<)**
 
 <details disabled>
@@ -357,6 +427,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from Rational use { (<) }
+assert 1/4r < 1/2r
+```
+
 ### Rational.**(>)**
 
 <details disabled>
@@ -383,6 +460,13 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from Rational use { (>) }
+assert 1/2r > 1/4r
+```
+
 ### Rational.**(<=)**
 
 <details disabled>
@@ -409,6 +493,18 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is less than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from Rational use { (<=) }
+assert 1/4r <= 1/2r
+```
+
+```grain
+from Rational use { (<=) }
+assert 1/2r <= 1/2r
+```
+
 ### Rational.**(>=)**
 
 <details disabled>
@@ -435,3 +531,15 @@ Returns:
 |----|-----------|
 |`Bool`|`true` if the first value is greater than or equal to the second value or `false` otherwise|
 
+Examples:
+
+```grain
+from Rational use { (>=) }
+assert 1/2r >= 1/4r
+```
+
+```grain
+from Rational use { (>=) }
+assert 1/2r >= 1/2r
+```
+