Merge pull request #5 from enaut/copilot/research-turtle-lib-architecture

Align turtle-lib API docs with actual speed/reset/coordinate/heading semantics

turtle-lib/src/builders.rs

@@ -349,6 +349,10 @@ impl TurtlePlan {
     /// - `180°` points left (west)
     /// - `270°` points down (south)
     ///
+    /// Internally, turtle heading is stored in radians in a Y-down render space.
+    /// This method converts from user-facing degrees (Y-up mental model) to that
+    /// internal representation.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -366,6 +370,8 @@ impl TurtlePlan {
     /// }
     /// ```
     pub fn set_heading<T: Into<Degrees>>(&mut self, heading: T) -> &mut Self {
+        // Convert user-facing turtle heading (degrees, Y-up mental model)
+        // to internal radians used by the render-space pipeline.
         self.queue
             .push(TurtleCommand::SetHeading(-heading.into().as_radians()));
         self
@@ -610,11 +616,14 @@ impl TurtlePlan {
     /// 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:
+    /// Coordinates use turtle-style Cartesian space:
     /// - `(0, 0)` is at the center
     /// - Positive x goes right
     /// - Positive y goes up
     ///
+    /// Internally, Macroquad uses Y-down screen coordinates; this command
+    /// performs the Y-axis conversion when executed.
+    ///
     /// # Examples
     ///
     /// ```no_run
@@ -677,7 +686,7 @@ impl TurtlePlan {
 
     /// Resets the turtle to its default state.
     ///
-    /// This clears all drawings, clears the animation queue, and resets all turtle parameters:
+    /// This clears all drawings, clears active fill state, and resets turtle parameters:
     /// - Position: (0, 0)
     /// - Heading: 0° (facing right)
     /// - Pen: down
@@ -688,6 +697,8 @@ impl TurtlePlan {
     /// - Shape: arrow
     /// - Speed: default
     ///
+    /// Note: queued commands are not removed; `reset()` itself is a command in the queue.
+    ///
     /// # Examples
     ///
     /// ```no_run

turtle-lib/src/commands.rs

@@ -34,7 +34,9 @@ pub enum TurtleCommand {
 
     // Position
     Goto(Coordinate),
-    /// Heading stored as radians — already converted by the builder.
+    /// Heading stored as internal radians (Y-down render-space convention).
+    /// Values passed via `TurtlePlan::set_heading` are converted from
+    /// user-facing degrees before this command is enqueued.
     SetHeading(Radians),
 
     // Visibility

turtle-lib/src/general.rs

@@ -13,7 +13,11 @@ pub use length::Length;
 /// Precision type for calculations
 pub type Precision = f32;
 
-/// 2D coordinate in screen space
+/// 2D coordinate value (`Vec2`) used by turtle commands and state.
+///
+/// Coordinate orientation depends on API context:
+/// - `go_to()` input uses turtle-style coordinates (Y+ is up)
+/// - internal render-space state uses Macroquad-style Y-down coordinates
 pub type Coordinate = Vec2;
 
 /// Visibility flag for turtle

turtle-lib/src/lib.rs

@@ -215,7 +215,7 @@ impl TurtleApp {
     ///
     /// Speed is controlled by `SetSpeed` commands in the queue.
     /// Use `set_speed()` on the turtle plan to set animation speed.
-    /// Speed >= 999 = instant mode, speed < 999 = animated mode.
+    /// Speed >= 1000 = instant mode, speed < 1000 = animated mode.
     ///
     /// # Arguments
     /// * `queue` - The command queue to execute
@@ -228,7 +228,7 @@ impl TurtleApp {
     ///
     /// Speed is controlled by `SetSpeed` commands in the queue.
     /// Use `set_speed()` on the turtle plan to set animation speed.
-    /// Speed >= 999 = instant mode, speed < 999 = animated mode.
+    /// Speed >= 1000 = instant mode, speed < 1000 = animated mode.
     ///
     /// # Arguments
     /// * `turtle_id` - The ID of the turtle to control