From c20bae1a9b6b1ea6fa09c28a9434e624b8e51cf8 Mon Sep 17 00:00:00 2001
From: Fantix King <fantix.king@gmail.com>
Date: Sun, 10 Mar 2024 22:37:17 -0400
Subject: [PATCH] CRF: add doc string

---
 assertion/assertion.mbt | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/assertion/assertion.mbt b/assertion/assertion.mbt
index 610aea26d..4c3492d11 100644
--- a/assertion/assertion.mbt
+++ b/assertion/assertion.mbt
@@ -95,6 +95,21 @@ test "assert_true.false" {
   assert_ne(assert_true(false), Ok(()))?
 }
 
+/// Assert referential equality of two values.
+///
+/// Returns Ok if the two arguments are the same object by reference, using the
+/// `===` operator; raises an Error otherwise. Certain objects may be equal by
+/// value, but they are different objects in the memory. This function checks
+/// the latter.
+///
+/// # Examples
+///
+/// ```
+/// let a = "4" + "2"
+/// let b = "4" + "2"
+/// assert_is(a, a)?  // this is okay
+/// assert_is(a, b)?  // yields an error
+/// ```
 pub fn assert_is[T : Debug](a : T, b : T) -> Result[Unit, String] {
   if a === b {
     Ok(())
@@ -119,6 +134,21 @@ test "assert_is.is.not" {
   assert_ne(assert_is(s1, s2), Ok(()))?
 }
 
+/// Assert referential inequality of two values.
+///
+/// Returns Ok if the two arguments are NOT the same object by reference, using
+/// the `===` operator; raises an Error otherwise. Certain objects may be equal
+/// by value, but they are different objects in the memory. This function
+/// checks the latter.
+///
+/// # Examples
+///
+/// ```
+/// let a = "4" + "2"
+/// let b = "4" + "2"
+/// assert_is_not(a, b)?  // this is okay
+/// assert_is_not(a, a)?  // yields an error
+/// ```
 pub fn assert_is_not[T : Debug](a : T, b : T) -> Result[Unit, String] {
   if not(a === b) {
     Ok(())