Adding docstrings for array, assert and panic macros (#6627)

crates/cairo-lang-semantic/src/inline_macros/array.rs

@@ -6,6 +6,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 indoc::indoc;
 
 #[derive(Debug, Default)]
 pub struct ArrayMacro;
@@ -49,4 +50,34 @@ impl InlineMacroExprPlugin for ArrayMacro {
             diagnostics: vec![],
         }
     }
+
+    fn documentation(&self) -> Option<String> {
+        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
+            - Elements must be of the same type or convertible to a common type.
+            - Elements are added in the order provided.
+            "#}
+            .to_string(),
+        )
+    }
 }

crates/cairo-lang-semantic/src/inline_macros/assert.rs

@@ -9,7 +9,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 indoc::formatdoc;
+use indoc::{formatdoc, indoc};
 
 /// Macro for assertion.
 #[derive(Default, Debug)]
@@ -111,4 +111,44 @@ impl InlineMacroExprPlugin for AssertMacro {
             diagnostics: vec![],
         }
     }
+
+    fn documentation(&self) -> Option<String> {
+        Some(
+            indoc! {r#"
+            Asserts that a condition is true at runtime.
+            The `assert!` macro checks a boolean expression; if it evaluates to `false`, \ 
+            it panics with an optional custom error message. Useful for debugging and \ 
+            ensuring conditions hold during execution.
+
+            # Syntax
+            ```cairo
+            assert!(condition);
+            assert!(condition, "error message");
+            assert!(condition, "formatted error: {}", value);
+            ```
+            # Parameters
+            - `condition`: A boolean expression to evaluate.
+            - `format_string` (optional): A string literal for format placeholders.
+            - `args` (optional): Values for placeholders in `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);
+            assert!(x >= 0, "Invalid value: x = {x}");
+            // Panics with "Invalid value: x = -1."
+            ```
+            # Notes
+            - Use to catch programming errors and enforce invariants.
+            - May impact performance; consider `debug_assert!` for debug-only checks.
+            - For recoverable errors, prefer using `Result` or `Option` instead of panicking.
+            "#}
+            .to_string(),
+        )
+    }
 }

crates/cairo-lang-semantic/src/inline_macros/consteval_int.rs

@@ -7,6 +7,7 @@ use cairo_lang_filesystem::ids::{CodeMapping, CodeOrigin};
 use cairo_lang_filesystem::span::{TextOffset, TextSpan, TextWidth};
 use cairo_lang_syntax::node::db::SyntaxGroup;
 use cairo_lang_syntax::node::{TypedStablePtr, TypedSyntaxNode, ast};
+use indoc::indoc;
 use num_bigint::BigInt;
 
 #[derive(Debug, Default)]
@@ -61,6 +62,31 @@ impl InlineMacroExprPlugin for ConstevalIntMacro {
             diagnostics,
         }
     }
+
+    fn documentation(&self) -> Option<String> {
+        Some(
+            indoc! {r#"
+            Evaluates an integer expression at compile time.
+            The `consteval_int!` macro computes an integer expression \ 
+            during compilation and replaces itself with the computed value.
+            This macro is deprecated; use const expressions directly instead.
+    
+            # Syntax
+            ```cairo
+            consteval_int!(expression)
+            ```
+            # Parameters
+            - `expression`: An integer expression to evaluate at compile time.
+    
+            # Examples
+            ```cairo
+            let x = consteval_int!(2 + 3); // Equivalent to: let x = 5;
+            let y = consteval_int!(4 * 5); // Equivalent to: let y = 20;
+            ```
+            "#}
+            .to_string(),
+        )
+    }
 }
 
 /// Compute the actual value of an integer expression, or fail with diagnostics.

crates/cairo-lang-semantic/src/inline_macros/panic.rs

@@ -7,7 +7,7 @@ use cairo_lang_defs::plugin_utils::{try_extract_unnamed_arg, unsupported_bracket
 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 indoc::{formatdoc, indoc};
 use num_bigint::BigUint;
 
 use super::write::FELT252_BYTES;
@@ -131,4 +131,49 @@ impl InlineMacroExprPlugin for PanicMacro {
             diagnostics: vec![],
         }
     }
+
+    fn documentation(&self) -> Option<String> {
+        Some(
+            indoc! {r#"
+            Terminates the program immediately with an error message.
+            The `panic!` macro halts execution when an unrecoverable error \ 
+            occurs. It prints an error message and exits the program. \ 
+            Accepts a format string and arguments, similar to `format!`, \ 
+            for detailed error messages.
+
+            # Syntax
+            ```cairo
+            panic!();
+            panic!("error message");
+            panic!("formatted error: {}", value);
+            ```
+            # Behavior
+            - Without arguments, panics with a default message.
+            - With a message or formatted string, panics with that message.
+            - Constructs the panic message at runtime using the 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".
+            }
+            let x = -1;
+            assert!(x >= 0, "Invalid value: x = {}", x);
+            assert!(x >= 0, "Invalid value: x = {x}");
+            // Panics with "Invalid value: x = -1."
+            ```
+    
+            # Notes
+            - Use `panic!` only for unrecoverable errors.
+            - In library code, prefer returning `Result` or `Option` to let callers handle errors.
+            - Avoid using `panic!` for control flow or expected error conditions.
+            "#}
+            .to_string(),
+        )
+    }
 }