document macros.rs #13

src/macros.rs

@@ -1,3 +1,24 @@
+/// Declares a struct that implements the `Event` trait.
+///
+/// This macro simplifies the creation of event types used within OSUI's reactive system.
+///
+/// # Variants
+///
+/// - `event!(Name)`
+///   Defines a unit struct named `Name`.
+///
+/// - `event!(Name { ... })`
+///   Defines a named struct with fields.
+///
+/// - `event!(Name (...))`
+///   Defines a tuple struct.
+///
+/// # Examples
+/// ```rust
+/// event!(Clicked);
+/// event!(Resized { width: u32, height: u32 });
+/// event!(Moved(u32, u32));
+/// ```
 #[macro_export]
 macro_rules! event {
     ($name:ident) => {
@@ -36,6 +57,28 @@ macro_rules! event {
     };
 }
 
+/// Declares a struct that implements the `Component` trait.
+///
+/// Components allow widgets to extend their behavior or contain additional data.
+/// This macro helps avoid boilerplate when defining new components.
+///
+/// # Variants
+///
+/// - `component!(Name)`
+///   Defines a unit struct.
+///
+/// - `component!(Name { ... })`
+///   Defines a named struct with fields.
+///
+/// - `component!(Name (...))`
+///   Defines a tuple struct.
+///
+/// # Examples
+/// ```rust
+/// component!(Focusable);
+/// component!(Tooltip { text: String });
+/// component!(Size(u32, u32));
+/// ```
 #[macro_export]
 macro_rules! component {
     ($name:ident) => {
@@ -86,35 +129,29 @@ macro_rules! component {
     };
 }
 
-/// Macro to create an event handler closure that calls a method on `self`
+/// Creates an event handler closure that calls a method on `self`.
 ///
-/// This macro automates the pattern of capturing `self` as a raw pointer,
+/// Useful when you need to register `'static` event handlers that interact with the current instance.
-/// then passing an event to a method on `self` inside an unsafe closure.
 ///
-/// # Parameters
+/// # Arguments
-/// - `$self_ty`: The self type.
+/// - `$self_ty`: The type of `self`.
-/// - `$self`: The instance variable (usually `self`) to call the method on.
+/// - `$self`: The instance variable (usually `self`) being used.
-/// - `$events`: The event source which has an `.on` method to register the handler.
+/// - `$events`: The event source object with an `.on` method.
-/// - `$method`: The method name on `self` to call when an event occurs.
+/// - `$method`: The method to call when an event is received.
 ///
-/// # Usage
+/// # Example
 /// ```rust
-/// event_handler!(self, events, on_keypress);
+/// event_handler!(Self, self, events, on_event);
 /// ```
-///
+/// Expands roughly to:
-/// This expands roughly to:
 /// ```rust
 /// let self_ref = self as *mut Self;
-/// events.on(move |event| unsafe { (*self_ref).on_keypress(event) });
+/// events.on(move |es, e| unsafe { (*self_ref).on_event(es, e) });
 /// ```
 ///
 /// # Safety
-/// This macro uses `unsafe` code because it dereferences a raw pointer inside the closure.
+/// This macro uses `unsafe` code to cast `self` to a raw pointer and dereference it.
-/// Ensure that the `self` reference lives at least as long as the closure to avoid undefined behavior.
+/// Make sure the reference is valid for the closure’s lifetime.
-///
-/// # Why use raw pointers here?
-/// Often, event handlers require `'static` closures, but `self` is a stack reference.
-/// Capturing `self` directly is not possible, so this workaround uses a raw pointer.
 #[macro_export]
 macro_rules! event_handler {
     ($self_ty:ty, $self:ident, $events:ident, $method:ident) => {{
@@ -123,6 +160,26 @@ macro_rules! event_handler {
     }};
 }
 
+/// Creates a `Transform` with property overrides.
+///
+/// Each key-value pair sets a field on a `Transform` struct.
+///
+/// # Example
+/// ```rust
+/// let t = transform!(
+///     x: 10,
+///     y: 20,
+///     scale: 1.5,
+/// );
+/// ```
+///
+/// This expands to:
+/// ```rust
+/// let mut t = Transform::new();
+/// t.x = 10.into();
+/// t.y = 20.into();
+/// t.scale = 1.5.into();
+/// ```
 #[macro_export]
 macro_rules! transform {
     ($($f:ident: $v:expr),* $(,)?) => {{
@@ -132,6 +189,22 @@ macro_rules! transform {
     }};
 }
 
+/// Constructs an `Rsx` tree using declarative syntax.
+///
+/// This macro is similar to JSX in UI frameworks, allowing you to nest widgets and assign components or dependencies.
+/// It expands into a tree of `RsxElement` objects.
+///
+/// Internally calls the recursive `rsx_inner!` macro.
+///
+/// # Example
+/// ```rust
+/// rsx! {
+///     "Hello"
+///     static Label { } ("Text")
+///     %state Label { }
+///     @Velocity(20, 0); Transform::new(); "Moving Text"
+/// }
+/// ```
 #[macro_export]
 macro_rules! rsx {
     ($($inner:tt)*) => {{
@@ -143,6 +216,28 @@ macro_rules! rsx {
     }};
 }
 
+/// Internal macro used by `rsx!` to recursively build `Rsx` trees.
+///
+/// This macro handles various syntactic forms used in the declarative layout system:
+///
+/// - Static text or components
+/// - Dynamic widgets with dependencies (`%dep`)
+/// - Component annotations (`@comp`)
+/// - Argument passing to constructors
+/// - Nesting and expansion from other `Rsx` blocks
+///
+/// **This macro is not intended for direct use**; use `rsx!` instead.
+///
+/// # Example expansion
+/// ```rust
+/// rsx! {
+///     static Label { } ("Title")
+///     %state Label { inner }
+///     "Text"
+/// }
+/// ```
+///
+/// Would produce a nested `Rsx` tree of static and dynamic widgets.
 #[macro_export]
 macro_rules! rsx_inner {
     // static