Apply suggestions from code review

Add a compile-time error indicating the need to use `features unstable`.
Rephrase some documentation and tweak minor things here and there.

Co-authored-by: Sunjay Varma <[email protected]>

Author: PaulDance

examples/flower.rs

@@ -4,6 +4,10 @@
 //! They both provide the ability to draw a circular arc defined by the given `radius` and `extent`
 //! parameters, while the first makes the turtle draw it to the left and the second to the right.
 
+// To run this example, use the command: cargo run --features unstable --example flower
+#[cfg(all(not(feature = "unstable")))]
+compile_error!("This example relies on unstable features. Run with `--features unstable`");
+
 use turtle::{Angle, Distance, Drawing};
 
 const TURTLE_SPEED: &str = "faster";
@@ -74,9 +78,12 @@ fn main() {
 
         // Right leaf.
         turtle.right(RIGHT_LEAF_INCLINATION);
-        turtle.arc_right(RIGHT_LEAF_BOTTOM_RADIUS, RIGHT_LEAF_BOTTOM_EXTENT);
+        // Note that `arc_left` with a negative radius is the same as calling `arc_right`.
+        // This is used below for illustration purposes only. You'd probably want to use
+        // `arc_right` in real code.
+        turtle.arc_left(-RIGHT_LEAF_BOTTOM_RADIUS, RIGHT_LEAF_BOTTOM_EXTENT);
         turtle.right(RIGHT_LEAF_INCLINATION);
-        turtle.arc_right(RIGHT_LEAF_TOP_RADIUS, -RIGHT_LEAF_TOP_EXTENT);
+        turtle.arc_left(-RIGHT_LEAF_TOP_RADIUS, -RIGHT_LEAF_TOP_EXTENT);
 
         // Trunk.
         turtle.end_fill();

src/ipc_protocol/protocol.rs

@@ -368,15 +368,17 @@ impl ProtocolClient {
     }
 
     pub async fn circular_arc(&self, id: TurtleId, radius: Distance, extent: Radians, direction: RotationDirection) {
-        if radius.is_normal() && extent.is_normal() {
-            let steps = 250;    // Arbitrary value for now.
-            let step = radius.abs() * extent.to_radians() / steps as f64;
-            let rotation = radius.signum() * extent / steps as f64;
-
-            for _ in 0..steps {
-                self.move_forward(id, step).await;
-                self.rotate_in_place(id, rotation, direction).await;
-            }
+        if !radius.is_normal() || !extent.is_normal() {
+            return;
+        }
+
+        let steps = 250;    // Arbitrary value for now.
+        let step = radius.abs() * extent.to_radians() / steps as f64;
+        let rotation = radius.signum() * extent / steps as f64;
+
+        for _ in 0..steps {
+            self.move_forward(id, step).await;
+            self.rotate_in_place(id, rotation, direction).await;
         }
     }
 

src/turtle.rs

@@ -210,26 +210,20 @@ impl Turtle {
     /// thus globally turning counterclockwise.
     ///
     /// It is configured through the `radius` and `extent` arguments:
-    ///  * `radius` places the center of the arc itself `Distance` units away from the left of the
+    ///  * `radius` places the center of the arc itself `radius` units away from the left of the
     ///    turtle, with respect to its current orientation. When negative, it does so to the right.
     ///  * `extent` controls how much of the arc is to be drawn, that is to say the `Angle` that
     ///    forms the circular portion of the given `radius`. When negative, the turtle moves
     ///    backwards instead, but it still goes to its left. It can also be greater than the
     ///    turtle's current angle unit domain limit, i.e. 360° when using degrees or 2π when using
     ///    radians: the turtle will simply continue to draw until the complete angle is reached.
     ///
-    /// This method does *nothing* if either one of the provided arguments is not "normal" in the
-    /// sense of [floating-point numbers' definition](f64::is_normal) of it.
-    ///
     /// # Example
     ///
     /// ```rust
     /// # use turtle::Turtle;
     /// let mut turtle = Turtle::new();
     ///
-    /// // No movement when anormal.
-    /// turtle.arc_left(0.0, 1.0);
-    /// turtle.arc_left(f64::NAN, -f64::INFINITY);
     /// assert_eq!(turtle.position(), [0.0, 0.0].into());
     /// assert_eq!(turtle.heading(), 90.0);
     ///
@@ -272,26 +266,20 @@ impl Turtle {
     /// thus globally turning clockwise.
     ///
     /// It is configured through the `radius` and `extent` arguments:
-    ///  * `radius` places the center of the arc itself `Distance` units away from the right of the
+    ///  * `radius` places the center of the arc itself `radius` units away from the right of the
     ///    turtle, with respect to its current orientation. When negative, it does so to the left.
     ///  * `extent` controls how much of the arc is to be drawn, that is to say the `Angle` that
     ///    forms the circular portion of the given `radius`. When negative, the turtle moves
     ///    backwards instead, but it still goes to its right. It can also be greater than the
     ///    turtle's current angle unit domain limit, i.e. 360° when using degrees or 2π when using
     ///    radians: the turtle will simply continue to draw until the complete angle is reached.
     ///
-    /// This method does *nothing* if either one of the provided arguments is not "normal" in the
-    /// sense of [floating-point numbers' definition](f64::is_normal) of it.
-    ///
     /// # Example
     ///
     /// ```rust
     /// # use turtle::Turtle;
     /// let mut turtle = Turtle::new();
     ///
-    /// // No movement when anormal.
-    /// turtle.arc_right(0.0, 1.0);
-    /// turtle.arc_right(f64::NAN, -f64::INFINITY);
     /// assert_eq!(turtle.position(), [0.0, 0.0].into());
     /// assert_eq!(turtle.heading(), 90.0);
     ///