docs: add docs for char to intrinsics

builtin/char.mbt

@@ -13,6 +13,25 @@
 // limitations under the License.
 
 ///|
+/// Calculates the difference between the Unicode code points of two characters.
+///
+/// Parameters:
+///
+/// * `self` : The first character whose code point serves as the minuend.
+/// * `other` : The second character whose code point serves as the subtrahend.
+///
+/// Returns an integer representing the difference between the Unicode code
+/// points of the two characters.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "Char::op_sub" {
+///   let a = 'b'
+///   let b = 'a'
+///   inspect!(a - b, content="1") // Unicode point of 'b' (98) minus 'a' (97)
+/// }
+/// ```
 pub fn Char::op_sub(self : Char, that : Char) -> Int {
   self.to_int() - that.to_int()
 }

builtin/console.mbt

@@ -19,11 +19,42 @@ fn println_mono(s : String) -> Unit = "%println"
 fn any_to_string[T](any : T) -> String = "%any.to_string"
 
 ///|
+/// Prints any value that implements the `Show` trait to the standard output,
+/// followed by a newline.
+///
+/// Parameters:
+///
+/// * `value` : The value to be printed. Must implement the `Show` trait.
+///
+/// Example:
+///
+/// ```moonbit skip
+/// test "println" {
+///   println(42)
+///   println("Hello, World!")
+///   println([1, 2, 3])
+/// }
+/// ```
 pub fn println[T : Show](input : T) -> Unit {
   println_mono(input.to_string())
 }
 
 ///|
+/// Prints a value to the standard output and appends a newline.
+///
+/// Parameters:
+///
+/// * `input` : The value to be printed. Must implement the `Show` trait.
+///
+/// Example:
+///
+/// ```moonbit skip
+/// test "print" {
+///   println(42)
+///   println("Hello, World!")
+/// }
+/// ```
+///
 /// @alert deprecated "Use `println` instead"
 /// @coverage.skip
 pub fn print[T : Show](input : T) -> Unit {
@@ -43,9 +74,51 @@ pub fn dump[T](t : T, name? : String, loc~ : SourceLoc = _) -> T {
 }
 
 ///|
+/// Represents an error type used by the `inspect!` function to indicate failures
+/// in value inspection. Contains a string message describing the nature of the
+/// inspection failure.
+///
+/// Returns a type constructor that creates an error type from a string message.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "inspect/failure" {
+///   let x : Int = 42
+///   inspect!(x, content="42") // Raises InspectError with detailed failure message
+/// }
+/// ```
 pub(all) type! InspectError String
 
 ///|
+/// Tests if the string representation of an object matches the expected content.
+/// Used primarily in test cases to verify the correctness of `Show`
+/// implementations and program outputs.
+///
+/// Parameters:
+///
+/// * `object` : The object to be inspected. Must implement the `Show` trait.
+/// * `content` : The expected string representation of the object. Defaults to
+/// an empty string.
+/// * `location` : Source code location information for error reporting.
+/// Automatically provided by the compiler.
+/// * `arguments_location` : Location information for function arguments in
+/// source code. Automatically provided by the compiler.
+///
+/// Throws an `InspectError` if the actual string representation of the object
+/// does not match the expected content. The error message includes detailed
+/// information about the mismatch, including source location and both expected
+/// and actual values.
+///
+/// Example:
+///
+/// ```moonbit skip
+/// test "inspect/basic" {
+///   inspect!(42, content="42")
+///   inspect!("hello", content="hello")
+///   inspect!([1, 2, 3], content="[1, 2, 3]")
+/// }
+/// ```
 pub fn inspect(
   obj : &Show,
   content~ : String = "",
@@ -65,7 +138,22 @@ pub fn inspect(
 }
 
 ///|
-// Used by test driver
+/// Represents an error that occurs during snapshot testing. Contains a string
+/// message describing the error.
+///
+/// Used internally by the test driver to handle snapshot-related errors. Not
+/// intended for direct use by end users.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "SnapshotError" {
+///   let err : SnapshotError = SnapshotError("failed to load snapshot")
+///   match err {
+///     SnapshotError(msg) => assert_eq!(msg, "failed to load snapshot")
+///   }
+/// }
+/// ```
 pub(all) type! SnapshotError String
 
 test "panic error case of inspect" {

builtin/failure.mbt

@@ -13,9 +13,50 @@
 // limitations under the License.
 
 ///|
+/// Represents a generic test failure type used primarily in test assertions and
+/// validations.
+///
+/// Since this is a type definition using `type!` syntax, it creates an error
+/// type `Failure` that wraps a `String` value containing the failure message.
+///
+/// Parameters:
+///
+/// * `message` : A string describing the nature of the failure.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "Failure" {
+///   let err : Failure = Failure("Test assertion failed")
+///   match err {
+///     Failure(msg) => inspect!(msg, content="Test assertion failed")
+///   }
+/// }
+/// ```
 pub(all) type! Failure String
 
 ///|
+/// Raises a `Failure` error with a given message and source location.
+///
+/// Parameters:
+///
+/// * `message` : A string containing the error message to be included in the
+/// failure.
+/// * `location` : The source code location where the failure occurred.
+/// Automatically provided by the compiler when not specified.
+///
+/// Returns a value of type `T` wrapped in a `Failure` error type.
+///
+/// Throws an error of type `Failure` with a message that includes both the
+/// source location and the provided error message.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "panic fail" {
+///   fail!("Something went wrong")
+/// }
+/// ```
 pub fn fail[T](msg : String, loc~ : SourceLoc = _) -> T!Failure {
   raise Failure("FAILED: \{loc} \{msg}")
 }

builtin/fixedarray.mbt

@@ -13,6 +13,27 @@
 // limitations under the License.
 
 ///|
+///
+/// Creates an iterator over the elements of a fixed-size array, providing
+/// sequential access to each element.
+///
+/// Parameters:
+///
+/// * `array` : The fixed-size array to iterate over.
+///
+/// Returns an iterator that yields each element of the array in order from first
+/// to last.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "FixedArray::iter" {
+///   let arr = FixedArray::make(3, 42)
+///   let mut sum = 0
+///   arr.iter().each(fn(x) { sum = sum + x })
+///   inspect!(sum, content="126")
+/// }
+/// ```
 /// @intrinsic %iter.from_array
 pub fn FixedArray::iter[T](self : FixedArray[T]) -> Iter[T] {
   Iter::new(fn(yield_) {
@@ -26,6 +47,27 @@ pub fn FixedArray::iter[T](self : FixedArray[T]) -> Iter[T] {
 }
 
 ///|
+/// Returns an iterator that yields both indices and values from the fixed array.
+/// The iterator provides pairs of `(index, value)` where indices start from 0
+/// and increment sequentially.
+///
+/// Parameters:
+///
+/// * `array` : The fixed array to iterate over.
+///
+/// Returns an iterator of type `Iter2[Int, T]` that yields tuples of indices and
+/// values from the array.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "FixedArray::iter2" {
+///   let arr = FixedArray::make(3, 10)
+///   let mut sum = 0
+///   arr.iter2().each(fn(i, x) { sum = sum + i + x })
+///   inspect!(sum, content="33") // (0 + 10) + (1 + 10) + (2 + 10) = 33
+/// }
+/// ```
 pub fn FixedArray::iter2[T](self : FixedArray[T]) -> Iter2[Int, T] {
   Iter2::new(fn(yield_) {
     for i, v in self {
@@ -38,6 +80,23 @@ pub fn FixedArray::iter2[T](self : FixedArray[T]) -> Iter2[Int, T] {
 }
 
 ///|
+/// Returns an empty fixed-size array of the specified type.
+///
+/// Parameters:
+///
+/// * `X` : The type parameter specifying the element type of the array.
+///
+/// Returns an empty fixed-size array of type `FixedArray[X]`.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "FixedArray::default" {
+///   let arr : FixedArray[Int] = FixedArray::default()
+///   inspect!(arr.length(), content="0")
+///   inspect!(arr.is_empty(), content="true")
+/// }
+/// ```
 pub fn FixedArray::default[X]() -> FixedArray[X] {
   []
 }
@@ -58,6 +117,34 @@ pub fn FixedArray::fill[T](self : FixedArray[T], value : T) -> Unit {
 }
 
 ///|
+/// Compares two fixed arrays lexicographically based on their elements. First
+/// compares the lengths of the arrays, then compares elements pairwise until a
+/// difference is found or all elements have been compared.
+///
+/// Parameters:
+///
+/// * `self` : The first fixed array to compare.
+/// * `other` : The second fixed array to compare.
+///
+/// Returns an integer that indicates the relative order:
+///
+/// * A negative value if `self` is less than `other`
+/// * Zero if `self` equals `other`
+/// * A positive value if `self` is greater than `other`
+///
+/// Example:
+///
+/// ```moonbit
+/// test "FixedArray::compare" {
+///   let arr1 = [1, 2, 3]
+///   let arr2 = [1, 2, 4]
+///   let arr3 = [1, 2]
+///   inspect!(arr1.compare(arr2), content="-1") // arr1 < arr2
+///   inspect!(arr2.compare(arr1), content="1") // arr2 > arr1
+///   inspect!(arr1.compare(arr3), content="1") // arr1 > arr3 (longer)
+///   inspect!(arr1.compare(arr1), content="0") // arr1 = arr1
+/// }
+/// ```
 pub fn compare[T : Compare](self : FixedArray[T], other : FixedArray[T]) -> Int {
   let len_self = self.length()
   let len_other = other.length()

builtin/fixedarray_block.mbt

@@ -69,6 +69,40 @@ fn UninitializedArray::unsafe_blit_fixed[T](
 }
 
 ///|
+/// Copies a sequence of elements from the source fixed array to a destination
+/// fixed array. The arrays may overlap, in which case the copy is performed in a
+/// way that preserves the data.
+///
+/// Parameters:
+///
+/// * `self` : The source fixed array from which elements will be copied.
+/// * `dst` : The destination fixed array where elements will be copied to.
+/// * `len` : The number of elements to copy.
+/// * `src_offset` : The starting position in the source array. Defaults to 0.
+/// * `dst_offset` : The starting position in the destination array. Defaults to
+/// 0.
+///
+/// Throws a panic if:
+///
+/// * `src_offset + len` exceeds the length of the source array
+/// * `dst_offset + len` exceeds the length of the destination array
+///
+/// Example:
+///
+/// ```moonbit
+/// test "FixedArray::blit_to" {
+///   let src = FixedArray::make(5, 1)
+///   let dst = FixedArray::make(5, 0)
+///   src.blit_to(dst, len=3, src_offset=1, dst_offset=2)
+///   inspect!(dst, content="[0, 0, 1, 1, 1]")
+/// }
+///
+/// test "panic FixedArray::blit_to/out_of_bounds" {
+///   let src = FixedArray::make(3, 1)
+///   let dst = FixedArray::make(3, 0)
+///   ignore(src.blit_to(dst, len=4)) // Panics: length out of bounds
+/// }
+/// ```
 pub fn FixedArray::blit_to[A](
   self : FixedArray[A],
   dst : FixedArray[A],