add examples

turtle-lib-macroquad/examples/dragon.rs

@@ -0,0 +1,93 @@
+//! Draw a dragon curve, more specifically a Heighway dragon.
+//!
+//! (https://en.wikipedia.org/wiki/Dragon_curve)
+//!
+//! As can be seen in the above Wikipedia article, the Heighway dragon can be
+//! constructed by repeatedly folding a strip of paper and looking at the
+//! directions of the folds/turns.
+//!
+//! Starting with a strip going left to right (l2r):
+//!
+//! start|--->---l2r--->---|end
+//!
+//! you might fold it like this:
+//!
+//! end|---<---r2l---<---\
+//! start|->---l2r--->---/
+//!
+//! Getting a l2r strip, followed by a left turn, followed by a r2l strip.
+//!
+//! Folding a right to left strip:
+//!
+//! end|---<---r2l---<---|start
+//!
+//! In the same way:
+//!
+//! start|-->---l2r--->---\
+//! end|----<---r2l---<---/
+//!
+//! Would give you a l2r, followed by a right turn, followed by a r2l strip.
+//!
+//! As you can see, the only difference between the two is the direction of
+//! the turn in the middle.
+//!
+//! This folding of paper is simulated by recursively calling the dragon(..)
+//! function, passing the direction of the turn for this fold as an angle
+//! (+90 for a right turn, -90 for a left turn).
+
+use turtle_lib_macroquad::*;
+
+#[turtle_main("Dragon Curve")]
+fn draw_dragon(turtle: &mut TurtlePlan) {
+    // Fast drawing
+    turtle.set_speed(1200);
+
+    // Start position
+    turtle.pen_up();
+    turtle.backward(160.0);
+    turtle.right(90.0);
+    turtle.forward(110.0);
+    turtle.pen_down();
+    turtle.set_pen_width(6.);
+
+    // Draw the dragon curve with 13 folds
+    dragon(turtle, -90.0, 13, 0.0, 255.0);
+
+    // Hide turtle when done
+    turtle.hide();
+}
+
+/// Draw the dragon curve by simulating folding a strip of paper
+///
+/// Arguments:
+/// `fold_direction`: The direction of the fold, +90 for a right, -90 for a
+/// left turn.
+/// `num_folds`: The number of times to fold the 'strip of paper'.
+/// `color_start`/`color_end`: The color at the start/end of this subsection
+/// of the curve as a number 0-255.
+fn dragon(
+    turtle: &mut TurtlePlan,
+    fold_direction: f32,
+    num_folds: usize,
+    color_start: f32,
+    color_end: f32,
+) {
+    let color_mid = (color_start + color_end) * 0.5;
+
+    if num_folds == 0 {
+        // Mapping a color number 0-255 to an RGB gradient
+        let red = ((color_mid - 128.0).abs() * 2.0).floor();
+        let green = color_mid;
+        let blue = 160.0;
+
+        turtle.set_pen_color(Color::new(red / 255.0, green / 255.0, blue / 255.0, 1.0));
+        turtle.forward(10.0);
+        return;
+    }
+
+    // Draw a left to right strip (which has a left turn in the middle)
+    dragon(turtle, -90.0, num_folds - 1, color_start, color_mid);
+    turtle.right(fold_direction);
+    // Draw a right to left strip (which has a right turn in the middle)
+    dragon(turtle, 90.0, num_folds - 1, color_mid, color_end);
+}

turtle-lib-macroquad/examples/sierpinski_triangle.rs

@@ -0,0 +1,98 @@
+//! Draws a Sierpiński triangle with automatic positioning and sizing.
+//!
+//! The Sierpiński triangle is a fairly simple self-similar fractal geometric shape: it consists of
+//! many nested equilateral triangles. More formally, such a triangle is itself three triangles of
+//! one level below and a size divided by two. Level zero means a simple equilateral triangle. The
+//! drawing procedure is as follows, for a given level and size:
+//!
+//!  * If level is 0
+//!    * Draw an equilateral triangle of the given size.
+//!  * otherwise
+//!    * Draw the half-sized level - 1 triangle at the bottom left.
+//!    * Go the start of the bottom-right slot.
+//!    * Draw a half-sized level - 1 triangle.
+//!    * Go to the start of the top slot.
+//!    * Draw a half-sized level - 1 triangle.
+//!
+//! That is relatively easy to implement, as long as you follow these steps and let recursion do
+//! the rest. Another little bonus this example provides is the ability to customize the drawing
+//! size: the triangle will stay correctly sized and positioned automatically.
+
+use macroquad::window::{screen_height, screen_width};
+use turtle_lib_macroquad::*;
+
+/// The number of levels to draw following the recursive procedure.
+const LEVELS: u8 = 9;
+/// Triangle size (adjust to fit nicely in window)
+const TRIANGLE_SIZE: f32 = 300.0;
+
+#[turtle_main("Sierpiński Triangle")]
+fn draw_sierpinski(turtle: &mut TurtlePlan) {
+    turtle.set_speed(1500); // Fast drawing
+    turtle.set_pen_width(0.2);
+
+    // Auto-sized procedure
+    sierpinski_triangle_auto(turtle, LEVELS);
+
+    // Hide turtle when done drawing in order to fully reveal the result
+    turtle.hide();
+}
+
+/// Recursive function drawing a Sierpiński triangle.
+///
+/// It will do it with the given `turtle` and start at its current position and heading. `level`
+/// is the depth of the drawing to be done, zero meaning a simple triangle. `size` is the length
+/// of the outermost triangle's sides.
+fn sierpinski_triangle(turtle: &mut TurtlePlan, level: u8, size: f32) {
+    // When level 0 is reached, just draw an equilateral triangle.
+    if level == 0 {
+        turtle.pen_down();
+
+        for _ in 0..3 {
+            turtle.forward(size);
+            turtle.left(120.0);
+        }
+
+        turtle.pen_up();
+    } else {
+        // Parameters for subsequent calls are the same.
+        let next_level = level - 1;
+        let next_size = size / 2.0;
+
+        // Bottom-left triangle.
+        sierpinski_triangle(turtle, next_level, next_size);
+
+        turtle.forward(next_size);
+
+        // Bottom-right triangle.
+        sierpinski_triangle(turtle, next_level, next_size);
+
+        turtle.left(120.0);
+        turtle.forward(next_size);
+        turtle.right(120.0);
+
+        // Top triangle.
+        sierpinski_triangle(turtle, next_level, next_size);
+
+        // Go back to the start.
+        turtle.right(120.0);
+        turtle.forward(next_size);
+        turtle.left(120.0);
+    }
+}
+
+/// Draws a Sierpiński triangle with automatic size and start point.
+///
+/// `level` is still required, it can't be computed automatically. However, given the used
+/// canvas size, it will compute the appropriate size and start point so the triangle gets
+/// centered and occupies as much drawing space as possible while staying in bounds.
+fn sierpinski_triangle_auto(turtle: &mut TurtlePlan, level: u8) {
+    let size = TRIANGLE_SIZE;
+
+    turtle.pen_up();
+    turtle.go_to((-screen_width() / 2.0 + 20.0, screen_height() / 2.0 - 20.0));
+    turtle.set_heading(0.0); // 0 = East (pointing right)
+
+    // The drawing itself.
+    sierpinski_triangle(turtle, level, size);
+}

turtle-lib-macroquad/examples/v1_0_0.rs

@@ -0,0 +1,126 @@
+//! Celebrates the 1.0.0 release of the original sunjay/turtle library.
+//!
+//! This example draws "1.0.0" with decorative background lines and filled shapes.
+//! Ported from the original sunjay/turtle example.
+
+use turtle_lib_macroquad::*;
+
+#[turtle_main("Version 1.0.0")]
+fn draw_version(turtle: &mut TurtlePlan) {
+    turtle.set_pen_width(10.0);
+    turtle.set_speed(999); // instant
+    turtle.pen_up();
+    turtle.go_to(vec2(350.0, 178.0));
+    turtle.pen_down();
+
+    bg_lines(turtle);
+
+    turtle.pen_up();
+    turtle.go_to(vec2(-270.0, -200.0));
+    turtle.set_heading(90.0);
+    turtle.pen_down();
+
+    turtle.set_speed(100); // normal
+    turtle.set_pen_color(BLUE);
+    // Cyan with alpha - using RGB values for Color::from("#00E5FF")
+    turtle.set_fill_color([0.0, 0.898, 1.0, 0.75]);
+
+    one(turtle);
+
+    turtle.set_speed(200); // faster
+
+    turtle.pen_up();
+    turtle.left(90.0);
+    turtle.backward(50.0);
+    turtle.pen_down();
+
+    small_circle(turtle);
+
+    turtle.pen_up();
+    turtle.backward(150.0);
+    turtle.pen_down();
+
+    zero(turtle);
+
+    turtle.pen_up();
+    turtle.backward(150.0);
+    turtle.pen_down();
+
+    small_circle(turtle);
+
+    turtle.pen_up();
+    turtle.backward(150.0);
+    turtle.pen_down();
+
+    zero(turtle);
+}
+
+fn bg_lines(turtle: &mut TurtlePlan) {
+    // Light green color for background lines (#76FF03)
+    turtle.set_pen_color([0.463, 1.0, 0.012, 1.0].into());
+    turtle.set_heading(165.0);
+    turtle.forward(280.0);
+
+    turtle.left(147.0);
+    turtle.forward(347.0);
+
+    turtle.right(158.0);
+    turtle.forward(547.0);
+
+    turtle.left(138.0);
+    turtle.forward(539.0);
+
+    turtle.right(168.0);
+    turtle.forward(477.0);
+
+    turtle.left(154.0);
+    turtle.forward(377.0);
+
+    turtle.right(158.0);
+    turtle.forward(329.0);
+}
+
+fn small_circle(turtle: &mut TurtlePlan) {
+    turtle.begin_fill();
+    for _ in 0..90 {
+        turtle.forward(1.0);
+        turtle.right(4.0);
+    }
+    turtle.end_fill();
+}
+
+fn one(turtle: &mut TurtlePlan) {
+    turtle.begin_fill();
+    for _ in 0..2 {
+        turtle.forward(420.0);
+        turtle.left(90.0);
+        turtle.forward(50.0);
+        turtle.left(90.0);
+    }
+    turtle.end_fill();
+}
+
+fn zero(turtle: &mut TurtlePlan) {
+    turtle.begin_fill();
+    for _ in 0..2 {
+        arc_right(turtle);
+        arc_forward(turtle);
+    }
+    turtle.end_fill();
+}
+
+fn arc_right(turtle: &mut TurtlePlan) {
+    // Draw an arc that moves right faster than it moves forward
+    for i in 0..90 {
+        turtle.forward(3.0);
+        turtle.right((90.0 - i as f32) / 45.0);
+    }
+}
+
+fn arc_forward(turtle: &mut TurtlePlan) {
+    // Draw an arc that moves forward faster than it moves right
+    for i in 0..90 {
+        turtle.forward(3.0);
+        turtle.right(i as f32 / 45.0);
+    }
+}

turtle-lib-macroquad/src/builders.rs

@@ -12,6 +12,25 @@ pub trait WithCommands {
 
 /// Trait for forward/backward movement
 pub trait DirectionalMovement: WithCommands {
+    /// Moves the turtle forward by the specified distance.
+    ///
+    /// The turtle moves in the direction of its current heading.
+    /// If the pen is down, a line is drawn.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Forward Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Move forward 100 pixels
+    ///     turtle.forward(100.0);
+    ///
+    ///     // Chain movements
+    ///     turtle.forward(50.0).right(90.0).forward(50.0);
+    /// }
+    /// ```
     fn forward<T>(&mut self, distance: T) -> &mut Self
     where
         T: Into<Precision>,
@@ -21,6 +40,25 @@ pub trait DirectionalMovement: WithCommands {
         self
     }
 
+    /// Moves the turtle backward by the specified distance.
+    ///
+    /// The turtle moves opposite to its current heading without changing
+    /// the heading direction. If the pen is down, a line is drawn.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Backward Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Move backward 100 pixels
+    ///     turtle.backward(100.0);
+    ///
+    ///     // Draw a line forward, then retrace backward
+    ///     turtle.forward(100.0).backward(50.0);
+    /// }
+    /// ```
     fn backward<T>(&mut self, distance: T) -> &mut Self
     where
         T: Into<Precision>,
@@ -33,6 +71,24 @@ pub trait DirectionalMovement: WithCommands {
 
 /// Trait for turning operations
 pub trait Turnable: WithCommands {
+    /// Turns the turtle left (counter-clockwise) by the specified angle in degrees.
+    ///
+    /// Changes the turtle's heading without moving its position.
+    /// Does not draw anything.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Left Turn Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Draw a square using left turns
+    ///     for _ in 0..4 {
+    ///         turtle.forward(100.0).left(90.0);
+    ///     }
+    /// }
+    /// ```
     fn left<T>(&mut self, angle: T) -> &mut Self
     where
         T: Into<Precision>,
@@ -42,6 +98,24 @@ pub trait Turnable: WithCommands {
         self
     }
 
+    /// Turns the turtle right (clockwise) by the specified angle in degrees.
+    ///
+    /// Changes the turtle's heading without moving its position.
+    /// Does not draw anything.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Right Turn Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Draw a triangle using right turns
+    ///     for _ in 0..3 {
+    ///         turtle.forward(100.0).right(120.0);
+    ///     }
+    /// }
+    /// ```
     fn right<T>(&mut self, angle: T) -> &mut Self
     where
         T: Into<Precision>,
@@ -54,6 +128,35 @@ pub trait Turnable: WithCommands {
 
 /// Trait for curved movement (circles)
 pub trait CurvedMovement: WithCommands {
+    /// Draws a circular arc turning to the left (counter-clockwise).
+    ///
+    /// The turtle draws a circular arc with the specified radius, sweeping through
+    /// the given angle. The circle center is positioned to the left of the turtle.
+    ///
+    /// # Parameters
+    ///
+    /// - `radius`: Distance from turtle to circle center (in pixels)
+    /// - `angle`: Arc sweep angle in degrees (360° = full circle)
+    /// - `steps`: Number of line segments to approximate the arc (more = smoother)
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Circle Left Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Draw a full circle
+    ///     turtle.circle_left(50.0, 360.0, 36);
+    ///
+    ///     // Filled circle
+    ///     turtle.pen_up().go_to(vec2(100.0, 0.0)).pen_down();
+    ///     turtle.set_fill_color(RED)
+    ///           .begin_fill()
+    ///           .circle_left(50.0, 360.0, 72)
+    ///           .end_fill();
+    /// }
+    /// ```
     fn circle_left<R, A>(&mut self, radius: R, angle: A, steps: usize) -> &mut Self
     where
         R: Into<Precision>,
@@ -70,6 +173,37 @@ pub trait CurvedMovement: WithCommands {
         self
     }
 
+    /// Draws a circular arc turning to the right (clockwise).
+    ///
+    /// The turtle draws a circular arc with the specified radius, sweeping through
+    /// the given angle. The circle center is positioned to the right of the turtle.
+    ///
+    /// # Parameters
+    ///
+    /// - `radius`: Distance from turtle to circle center (in pixels)
+    /// - `angle`: Arc sweep angle in degrees (360° = full circle)
+    /// - `steps`: Number of line segments to approximate the arc (more = smoother)
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Circle Right Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Draw an S-curve using both directions
+    ///     turtle.circle_left(50.0, 180.0, 36)
+    ///           .circle_right(50.0, 180.0, 36);
+    ///
+    ///     // Yin-yang pattern uses circle_left and circle_right
+    ///     turtle.set_fill_color(BLACK)
+    ///           .begin_fill()
+    ///           .circle_right(100.0, 180.0, 36)
+    ///           .circle_right(50.0, 180.0, 36)
+    ///           .circle_left(50.0, 180.0, 36)
+    ///           .end_fill();
+    /// }
+    /// ```
     fn circle_right<R, A>(&mut self, radius: R, angle: A, steps: usize) -> &mut Self
     where
         R: Into<Precision>,
@@ -94,6 +228,35 @@ pub struct TurtlePlan {
 }
 
 impl TurtlePlan {
+    /// Creates a new empty turtle command plan.
+    ///
+    /// This has to be used when not using the `turtle_main` macro.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// use turtle_lib_macroquad::*;
+    /// use macroquad::prelude::*;
+    ///
+    /// #[macroquad::main("Manual Setup")]
+    /// async fn main() {
+    ///     let mut turtle = TurtlePlan::new();
+    ///     turtle.forward(100.0).right(90.0).forward(100.0);
+    ///     
+    ///     let mut app = TurtleApp::new().with_commands(turtle.build());
+    ///     
+    ///     loop {
+    ///         clear_background(WHITE);
+    ///         app.update();
+    ///         app.render();
+    ///         
+    ///         if is_key_pressed(KeyCode::Escape) || is_key_pressed(KeyCode::Q) {
+    ///             break;
+    ///         }
+    ///         next_frame().await;
+    ///     }
+    /// }
+    /// ```
     #[must_use]
     pub fn new() -> Self {
         Self {
@@ -101,86 +264,394 @@ impl TurtlePlan {
         }
     }
 
-    #[must_use]
-    pub fn with_capacity(capacity: usize) -> Self {
-        Self {
-            queue: CommandQueue::with_capacity(capacity),
-        }
-    }
-
-    /// Set animation speed
-    /// - Values >= 999 = instant mode (no animation)
-    /// - Values < 999 = animated mode with specified pixels/second
+    /// Sets the animation speed for turtle movements.
+    ///
+    /// Speed controls how fast the turtle moves during animations:
+    /// - Values `>= 1000`: Instant mode - commands execute immediately without animation.
+    ///                    The bigger the number, the more segments are drawn per frame.
+    /// - Values `< 1000`: Animated mode - turtle moves at specified pixels per second
+    ///
+    /// You can dynamically switch between instant and animated modes during execution.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Speed Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Slow animation at 50 pixels/second
+    ///     turtle.set_speed(50.0)
+    ///           .forward(100.0);
+    ///
+    ///     // Switch to instant mode
+    ///     turtle.set_speed(1000.0)
+    ///           .forward(100.0);  // Executes immediately
+    /// }
+    /// ```
     pub fn set_speed(&mut self, speed: impl Into<AnimationSpeed>) -> &mut Self {
         self.queue.push(TurtleCommand::SetSpeed(speed.into()));
         self
     }
 
+    /// Sets the pen color for drawing lines.
+    ///
+    /// The pen color affects all subsequent drawing operations (forward, backward, circles)
+    /// until changed again. Does not affect fill color.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Pen Color Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Draw with predefined colors
+    ///     turtle.set_pen_color(RED)
+    ///           .forward(100.0)
+    ///           .set_pen_color(BLUE)
+    ///           .right(90.0)
+    ///           .forward(100.0);
+    /// }
+    /// ```
     pub fn set_pen_color(&mut self, color: Color) -> &mut Self {
         self.queue.push(TurtleCommand::SetColor(color));
         self
     }
 
+    /// Sets the pen width (thickness) for drawing lines.
+    ///
+    /// The width is measured in pixels. Default is typically 2.0.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Pen Width Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Thin line
+    ///     turtle.set_pen_width(1.0)
+    ///           .forward(100.0);
+    ///
+    ///     // Thick line
+    ///     turtle.set_pen_width(10.0)
+    ///           .forward(100.0);
+    /// }
+    /// ```
     pub fn set_pen_width(&mut self, width: Precision) -> &mut Self {
         self.queue.push(TurtleCommand::SetPenWidth(width));
         self
     }
 
+    /// Sets the turtle's absolute heading direction in degrees.
+    ///
+    /// - `0°` points to the right (east)
+    /// - `90°` points up (north)
+    /// - `180°` points left (west)
+    /// - `270°` points down (south)
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Heading Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Point upward
+    ///     turtle.set_heading(90.0)
+    ///           .forward(100.0);
+    ///
+    ///     // Point left
+    ///     turtle.set_heading(180.0)
+    ///           .forward(100.0);
+    /// }
+    /// ```
     pub fn set_heading(&mut self, heading: Precision) -> &mut Self {
         self.queue.push(TurtleCommand::SetHeading(heading));
         self
     }
 
+    /// Lifts the pen up so the turtle can move without drawing.
+    ///
+    /// When filling shapes, `pen_up()` also closes the current contour,
+    /// allowing you to create multi-contour fills (e.g., shapes with holes).
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Pen Up/Down Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Move without drawing
+    ///     turtle.pen_up()
+    ///           .forward(100.0)  // No line drawn
+    ///           .pen_down()
+    ///           .forward(100.0); // Line drawn
+    ///
+    ///     // Create a donut shape (outer circle with inner hole)
+    ///     turtle.set_fill_color(BLUE)
+    ///           .begin_fill()
+    ///           .circle_left(100.0, 360.0, 72)  // Outer circle
+    ///           .pen_up()  // Close first contour
+    ///           .go_to(vec2(0.0, -30.0))
+    ///           .pen_down()  // Start second contour
+    ///           .circle_left(30.0, 360.0, 36)   // Inner circle (becomes hole)
+    ///           .end_fill();
+    /// }
+    /// ```
     pub fn pen_up(&mut self) -> &mut Self {
         self.queue.push(TurtleCommand::PenUp);
         self
     }
 
+    /// Lowers the pen so the turtle draws when moving.
+    ///
+    /// This is the default state. When filling shapes, `pen_down()` starts
+    /// a new contour after `pen_up()` was called.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Pen Down Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     turtle.pen_up()
+    ///           .forward(50.0)    // Move without drawing
+    ///           .pen_down()       // Start drawing
+    ///           .forward(100.0);  // Line appears
+    /// }
+    /// ```
     pub fn pen_down(&mut self) -> &mut Self {
         self.queue.push(TurtleCommand::PenDown);
         self
     }
 
+    /// Hides the turtle cursor from view.
+    ///
+    /// The turtle will still execute commands and draw, but the cursor
+    /// (typically an arrow or triangle) won't be visible.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Hide Turtle Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     turtle.hide()  // Turtle cursor invisible
+    ///           .forward(100.0)
+    ///           .right(90.0)
+    ///           .forward(100.0);
+    /// }
+    /// ```
     pub fn hide(&mut self) -> &mut Self {
         self.queue.push(TurtleCommand::HideTurtle);
         self
     }
 
+    /// Shows the turtle cursor.
+    ///
+    /// Makes the turtle cursor visible if it was previously hidden.
+    /// This is the default state.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Show Turtle Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     turtle.hide()
+    ///           .forward(100.0)
+    ///           .show()  // Turtle becomes visible again
+    ///           .forward(100.0);
+    /// }
+    /// ```
     pub fn show(&mut self) -> &mut Self {
         self.queue.push(TurtleCommand::ShowTurtle);
         self
     }
 
+    /// Sets the turtle's shape using a `TurtleShape` object.
+    ///
+    /// For most use cases, prefer using `shape()` which accepts a `ShapeType` enum.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Shape Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    /// let custom_shape = ShapeType::Arrow.to_shape();
+    /// turtle.set_shape(custom_shape);
+    /// }
+    /// ```
     pub fn set_shape(&mut self, shape: TurtleShape) -> &mut Self {
         self.queue.push(TurtleCommand::SetShape(shape));
         self
     }
 
+    /// Sets the turtle's visual appearance.
+    ///
+    /// Available shapes: `Arrow`, `Triangle`, `Square`, `Circle`.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Shape Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Use different shapes
+    ///     turtle.shape(ShapeType::Arrow)
+    ///           .forward(50.0)
+    ///           .shape(ShapeType::Circle)
+    ///           .forward(50.0);
+    /// }
+    /// ```
     pub fn shape(&mut self, shape_type: ShapeType) -> &mut Self {
         self.set_shape(shape_type.to_shape())
     }
 
+    /// Starts recording a shape to be filled.
+    ///
+    /// All turtle movements between `begin_fill()` and `end_fill()` define
+    /// the shape's outline. The shape is filled using the fill color when
+    /// `end_fill()` is called.
+    ///
+    /// Multiple contours can be created using `pen_up()` and `pen_down()`.
+    /// The `EvenOdd` fill rule automatically creates holes for inner contours.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Fill Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Fill a square
+    ///     turtle.set_fill_color(BLUE)
+    ///           .begin_fill();
+    ///     for _ in 0..4 {
+    ///         turtle.forward(100.0).right(90.0);
+    ///     }
+    ///     turtle.end_fill();
+    ///
+    ///     // Fill a circle
+    ///     turtle.pen_up().go_to(vec2(150.0, 0.0)).pen_down();
+    ///     turtle.set_fill_color(RED)
+    ///           .begin_fill()
+    ///           .circle_left(50.0, 360.0, 36)
+    ///           .end_fill();
+    /// }
+    /// ```
     pub fn begin_fill(&mut self) -> &mut Self {
         self.queue.push(TurtleCommand::BeginFill);
         self
     }
 
+    /// Completes the fill operation started with `begin_fill()`.
+    ///
+    /// Closes the current shape and fills it with the fill color.
+    /// All contours recorded since `begin_fill()` are filled together.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("End Fill Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Triangle with fill
+    ///     turtle.set_fill_color(GREEN)
+    ///           .begin_fill();
+    ///     for _ in 0..3 {
+    ///         turtle.forward(100.0).right(120.0);
+    ///     }
+    ///     turtle.end_fill();
+    /// }
+    /// ```
     pub fn end_fill(&mut self) -> &mut Self {
         self.queue.push(TurtleCommand::EndFill);
         self
     }
 
+    /// Sets the color used to fill shapes.
+    ///
+    /// This affects all shapes filled with `begin_fill()`/`end_fill()`.
+    /// Independent from the pen color used for outlines.
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Fill Color Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Yellow fill with blue outline
+    ///     turtle.set_fill_color(YELLOW)
+    ///           .set_pen_color(BLUE)
+    ///           .begin_fill()
+    ///           .circle_left(50.0, 360.0, 36)
+    ///           .end_fill();
+    /// }
+    /// ```
     pub fn set_fill_color(&mut self, color: impl Into<Color>) -> &mut Self {
         self.queue
             .push(TurtleCommand::SetFillColor(Some(color.into())));
         self
     }
 
+    /// Moves the turtle to an absolute position.
+    ///
+    /// The turtle moves in a straight line to the specified coordinates.
+    /// If the pen is down, a line is drawn. The turtle's heading is not changed.
+    ///
+    /// Coordinates are in screen space:
+    /// - `(0, 0)` is at the center
+    /// - Positive x goes right
+    /// - Positive y goes down
+    ///
+    /// # Examples
+    ///
+    /// ```no_run
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// #[turtle_main("Goto Example")]
+    /// fn draw(turtle: &mut TurtlePlan) {
+    ///     // Draw a triangle by connecting points
+    ///     turtle.go_to(vec2(0.0, 0.0));
+    ///     turtle.go_to(vec2(100.0, 0.0));
+    ///     turtle.go_to(vec2(50.0, 86.6));
+    ///     turtle.go_to(vec2(0.0, 0.0));
+    /// }
+    /// ```
     pub fn go_to(&mut self, coord: impl Into<Coordinate>) -> &mut Self {
         self.queue.push(TurtleCommand::Goto(coord.into()));
         self
     }
 
+    /// Consumes the `TurtlePlan` and returns the command queue.
+    ///
+    /// Use this to finalize the turtle commands and pass them to `TurtleApp`.
+    /// This method consumes `self`, so the plan cannot be used afterward.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// # use turtle_lib_macroquad::*;
+    /// #
+    /// let mut turtle = TurtlePlan::new();
+    /// turtle.forward(100.0).right(90.0).forward(100.0);
+    ///
+    /// // Build and get the command queue
+    /// let commands = turtle.build();
+    /// # assert!(!commands.is_empty());
+    /// ```
     #[must_use]
     pub fn build(self) -> CommandQueue {
         self.queue