doc: some more builtin files

builtin/assert.mbt

@@ -20,13 +20,65 @@ fn debug_string[T : Show](t : T) -> String {
 }
 
 ///|
+/// Asserts that two values are equal. If they are not equal, raises a failure
+/// with a message containing the source location and the values being compared.
+///
+/// Parameters:
+///
+/// * `a` : First value to compare.
+/// * `b` : Second value to compare.
+/// * `loc` : Source location information to include in failure messages. This is
+/// usually automatically provided by the compiler.
+///
+/// Throws a `Failure` error if the values are not equal, with a message showing
+/// the location of the failing assertion and the actual values that were
+/// compared.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "assert_eq" {
+///   assert_eq!(1, 1)
+///   assert_eq!("hello", "hello")
+/// }
+/// 
+/// test "panic assert_eq/not_equal" {
+///   ignore(assert_eq!(1, 2)) // Will fail with message showing values and location
+/// }
+/// ```
 pub fn assert_eq[T : Eq + Show](a : T, b : T, loc~ : SourceLoc = _) -> Unit! {
   if a != b {
     fail!("FAILED: \{loc} `\{a} == \{b}`")
   }
 }
 
 ///|
+/// Asserts that two values of the same type are not equal. If the values are
+/// equal, raises a failure with a detailed error message including the source
+/// location and string representation of both values.
+///
+/// Parameters:
+///
+/// * `first` : The first value to compare.
+/// * `second` : The second value to compare.
+/// * `location` : Source location information for error reporting. Defaults to
+/// the current location.
+///
+/// Throws a `Failure` error if the values are equal. The error message includes
+/// the source location and string representations of both values.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "assert_not_eq" {
+///   assert_not_eq!(1, 2) // Passes
+///   assert_not_eq!(1, 1) // Fails with message showing values are equal
+/// }
+/// 
+/// test "panic assert_not_eq/equal_values" {
+///   ignore(assert_not_eq!(42, 42)) // Fails with detailed error message
+/// }
+/// ```
 pub fn assert_not_eq[T : Eq + Show](
   a : T,
   b : T,
@@ -40,13 +92,60 @@ pub fn assert_not_eq[T : Eq + Show](
 }
 
 ///|
+/// Asserts that the given boolean value is true. Throws an error with source
+/// location information if the assertion fails.
+///
+/// Parameters:
+///
+/// * `condition` : The boolean value to be checked.
+/// * `location` : The source location where the assertion is made. Defaults to
+/// the current location.
+///
+/// Throws a `Failure` error with a descriptive message including the source
+/// location if the condition is false.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "assert_true" {
+///   assert_true!(true)
+/// }
+/// 
+/// test "panic assert_true/false_condition" {
+///   ignore(assert_true!(false)) // Throws Failure
+/// }
+/// ```
 pub fn assert_true(x : Bool, loc~ : SourceLoc = _) -> Unit! {
   if not(x) {
     fail!("FAILED: \{loc} `\{x}` is not true")
   }
 }
 
 ///|
+/// Tests whether a boolean condition is false, throwing an error if the
+/// condition is true.
+///
+/// Parameters:
+///
+/// * `condition` : The boolean condition to test.
+/// * `location` : The source location where the assertion is made. Used in error
+/// messages.
+///
+/// Throws a `Failure` error if the condition is true. The error message includes
+/// the source location and the value that was expected to be false.
+///
+/// Example:
+///
+/// ```moonbit
+/// test "assert_false" {
+///   assert_false!(false)
+///   assert_false!(1 > 2)
+/// }
+/// 
+/// test "panic assert_false/with_true" {
+///   assert_false!(true) // This will fail with an error message
+/// }
+/// ```
 pub fn assert_false(x : Bool, loc~ : SourceLoc = _) -> Unit! {
   if x {
     let x = debug_string(x)

builtin/autoloc.mbt

@@ -13,9 +13,29 @@
 // limitations under the License.
 
 ///|
+/// Represents a source code location in a MoonBit program, containing
+/// information about the file path, line number, and column number. Used
+/// internally by the compiler for error reporting and debugging purposes.
+///
+/// This type is public to all packages but its internal representation is
+/// opaque. Users cannot construct values of this type directly; they are
+/// automatically created by the compiler when needed.
 pub(all) type SourceLoc
 
 ///|
+/// Converts a source location to its string representation.
+///
+/// Parameters:
+///
+/// * `source_location` : A source code location containing information about the
+/// file path, line number, and column number.
+///
+/// Returns a string representation of the source location, typically in the
+/// format "file:line:column".
+///
+/// Note: This function is primarily used internally by the compiler for error
+/// reporting and debugging purposes. Source locations are automatically created
+/// by the compiler when needed.
 pub fn SourceLoc::to_string(self : SourceLoc) -> String = "%loc_to_string"
 
 ///|
@@ -24,9 +44,23 @@ pub impl Show for SourceLoc with output(self, logger) {
 }
 
 ///|
+/// Represents a type for storing argument locations in source code. It is an
+/// array of optional source locations, where each element corresponds to an
+/// argument's location in the source code. Used internally by the compiler for
+/// error reporting and debugging purposes.
 pub(all) type ArgsLoc Array[SourceLoc?] derive(Show)
 
 ///|
+/// Converts an array of optional source locations to its JSON string
+/// representation. Each location in the array is either represented as a string
+/// if present, or "null" if absent.
+///
+/// Parameters:
+///
+/// * `self` : The array of optional source locations to be converted.
+///
+/// Returns a JSON array string where each element is either a string
+/// representation of a source location or "null".
 pub fn ArgsLoc::to_json(self : ArgsLoc) -> String {
   let buf = StringBuilder::new(size_hint=10)
   buf.write_char('[')