diff --git a/crates/cairo-lang-semantic/src/inline_macros/array.rs b/crates/cairo-lang-semantic/src/inline_macros/array.rs index 29b3b333df5..6201784cc31 100644 --- a/crates/cairo-lang-semantic/src/inline_macros/array.rs +++ b/crates/cairo-lang-semantic/src/inline_macros/array.rs @@ -5,7 +5,7 @@ use cairo_lang_defs::plugin::{ }; use cairo_lang_defs::plugin_utils::unsupported_bracket_diagnostic; use cairo_lang_syntax::node::db::SyntaxGroup; -use cairo_lang_syntax::node::{TypedSyntaxNode, ast}; +use cairo_lang_syntax::node::{ast, TypedSyntaxNode}; #[derive(Debug, Default)] pub struct ArrayMacro; @@ -49,4 +49,45 @@ impl InlineMacroExprPlugin for ArrayMacro { diagnostics: vec![], } } + + fn documentation(&self) -> Option { + Some( + indoc! {r#" + Creates a new array containing the provided elements. + + The `array!` macro allows you to create an array by specifying a list of elements. \ + The elements are added to a new array in the order they are provided. + + # Syntax + + ```cairo + array![element1, element2, element3, ...] + ``` + + # Returns + + An array containing the specified elements. + + # Examples + + ```cairo + let arr = array![]; // Creates an empty array. + + let arr = array![1, 2, 3]; // Creates an array containing 1, 2, and 3. + + let x = 5; + let y = 10; + let arr = array![x, y, x + y]; // Creates an array containing 5, 10, and 15. + ``` + + # Notes + + - All elements must be of the same type or compatible types that can be coerced to a common type. + - The macro internally uses `ArrayTrait::new()` to create a new array and `ArrayTrait::append()` to add each element. + - The order of the elements in the array is the same as the order they are provided in the macro. + + "#} + .to_string(), + ) + } } diff --git a/crates/cairo-lang-semantic/src/inline_macros/assert.rs b/crates/cairo-lang-semantic/src/inline_macros/assert.rs index ea576377c8e..da9cf22f84c 100644 --- a/crates/cairo-lang-semantic/src/inline_macros/assert.rs +++ b/crates/cairo-lang-semantic/src/inline_macros/assert.rs @@ -8,7 +8,7 @@ use cairo_lang_defs::plugin_utils::{ }; use cairo_lang_syntax::node::ast::WrappedArgList; use cairo_lang_syntax::node::db::SyntaxGroup; -use cairo_lang_syntax::node::{TypedStablePtr, TypedSyntaxNode, ast}; +use cairo_lang_syntax::node::{ast, TypedStablePtr, TypedSyntaxNode}; use indoc::formatdoc; /// Macro for assertion. @@ -111,4 +111,55 @@ impl InlineMacroExprPlugin for AssertMacro { diagnostics: vec![], } } + + fn documentation(&self) -> Option { + Some( + indoc! {r#" + Asserts that a condition is true at runtime. + + The `assert!` macro is used to check whether a boolean expression evaluates to `true`. \ + If the expression evaluates to `false`, the macro will cause the program to panic, \ + optionally displaying a custom error message. This is useful for debugging and ensuring \ + that certain conditions hold during execution. + + # Syntax + + ```cairo + assert!(condition); + assert!(condition, "error message"); + assert!(condition, "formatted error: {}", value); + ``` + + # Parameters + + - `condition`: A boolean expression to evaluate. The assertion passes if this expression is `true`. + - `format_string` (optional): A string literal that may include format placeholders. + - `args` (optional): Arguments corresponding to the format placeholders in the `format_string`. + + # Examples + + ```cairo + assert!(2 + 2 == 4); // Passes, does nothing. + + assert!(2 + 2 == 5); // Panics with "assertion failed: `2 + 2 == 5`." + + let age = 18; + assert!(age >= 21, "Age must be at least 21, found {}", age); + // Panics with "Age must be at least 21, found 18." + + let x = -1; + assert!(x >= 0, "Invalid value: x = {}", x); + // Panics with "Invalid value: x = -1." + ``` + + # Notes + + - **Use Cases**: Ideal for catching programming errors and enforcing invariants. + - **Performance**: Assertions can impact performance; consider using `debug_assert!` for checks in debug mode only. + - **Error Handling**: For recoverable errors, use proper error handling mechanisms like `Result` or `Option` instead of panicking. + + "#} + .to_string(), + ) + } } diff --git a/crates/cairo-lang-semantic/src/inline_macros/panic.rs b/crates/cairo-lang-semantic/src/inline_macros/panic.rs index 4288a3fb07d..cf6ac38e129 100644 --- a/crates/cairo-lang-semantic/src/inline_macros/panic.rs +++ b/crates/cairo-lang-semantic/src/inline_macros/panic.rs @@ -6,8 +6,8 @@ use cairo_lang_defs::plugin::{ use cairo_lang_defs::plugin_utils::{try_extract_unnamed_arg, unsupported_bracket_diagnostic}; use cairo_lang_syntax::node::ast::{Arg, WrappedArgList}; use cairo_lang_syntax::node::db::SyntaxGroup; -use cairo_lang_syntax::node::{TypedSyntaxNode, ast}; -use indoc::formatdoc; +use cairo_lang_syntax::node::{ast, TypedSyntaxNode}; +use indoc::{formatdoc, indoc}; use num_bigint::BigUint; use super::write::FELT252_BYTES; @@ -131,4 +131,55 @@ impl InlineMacroExprPlugin for PanicMacro { diagnostics: vec![], } } + + fn documentation(&self) -> Option { + Some( + indoc! {r#" + Terminates the program immediately with an error message. + + The `panic!` macro is used to halt execution when the program encounters an unrecoverable \ + error. It prints an error message to the standard error output and exits the program. \ + This macro accepts a format string and arguments, similar to the `format!` macro, allowing for \ + detailed error messages. + + # Syntax + + ```cairo + panic!(); + panic!("error message"); + panic!("formatted error: {}", value); + ``` + + # Behavior + + - If called without any arguments, it panics with a default message. + - If provided with a message or formatted string, it panics with the given message. + - The macro constructs the panic message at runtime using the provided format string and arguments. + + # Examples + + ```cairo + panic!(); // Panics with a default message. + + panic!("An unexpected error occurred."); // Panics with the provided message. + + let x = 10; + let y = 20; + if x + y != 30 { + panic!("Math is broken: {} + {} != 30", x, y); + // Panics with "Math is broken: 10 + 20 != 30". + } + ``` + + # Notes + + - Use `panic!` for unrecoverable errors where the program cannot safely continue. + - Panicking will terminate the current execution flow and unwind the stack, which may skip resource cleanup. + - In library code, prefer returning `Result` or `Option` to allow the caller to handle errors. + - Avoid using `panic!` for control flow or expected error conditions. + + "#} + .to_string(), + ) + } }