update num::geom::metric::angle

- rename `AngleDirection` variants: `CounterClockwise` to `Positive` and `Clockwise` to `Negative`.
  - add aliases from common jargons.
- update docs.

DOCS/CHANGELOG.md

@@ -9,7 +9,9 @@
   - sys: `AppEnv`, `ExtLog`
   - ui: `MiniquadEventHandlerExt`, `UiService`.
   - work: `ExtProcess`.
-- new consts: `FONT_3_3`, `FONT_3_5`, `FONT_5_6`.
+- new consts:
+  - media::font: `FONT_3_3`, `FONT_3_5`, `FONT_5_6`.
+  - `AngleDirection::{CounterClockwise, CCW, RightHandRule, RHR, Clockwise, CW, LeftHandRule, LHR}`
 - new types:
   - code: `ScopeGuard`.
   - data:
@@ -72,6 +74,8 @@
   - `LoggerConfig` to `LogConfig`.
   - `TextWrite` trait to `FmtWrite`.
   - re-exports: `Layout` to `MemLayout`, `LayoutError` to `MemLayoutError`.
+- rename variants:
+  - `AngleDirection`: `CounterClockwise` to `Positive`, `Clockwise` to `Negative`.
 - rename/move fns/methods:
   - from prngs: `next_state` method to `peek_next_state`.
   - `fmt_write`, `fmt_format` and `format_buf_args` to `Fmt::{write, format, format_buf`, respectively.

src/num/geom/metric/angle/impl/float.rs

@@ -100,8 +100,8 @@ macro_rules! impl_angle {
             /// Since the floating-point representation always maintains the sign
             /// the direction can't be undefined.
             pub const fn direction(self) -> AngleDirection {
-                use AngleDirection::{Clockwise, CounterClockwise};
-                if Float(self.turn).is_sign_negative() { Clockwise } else { CounterClockwise }
+                use AngleDirection::{Negative, Positive};
+                if Float(self.turn).is_sign_negative() { Negative } else { Positive }
             }
 
             /// Returns `true` if the angle has the given `direction`.
@@ -119,8 +119,8 @@ macro_rules! impl_angle {
             pub const fn with_direction(self, direction: AngleDirection) -> Self {
                 use AngleDirection as D;
                 match direction {
-                    D::CounterClockwise | D::Undefined => Self::new(Float(self.turn).abs().0),
-                    D::Clockwise => Self::new(Float(self.turn).neg_abs().0),
+                    D::Positive | D::Undefined => Self::new(Float(self.turn).abs().0),
+                    D::Negative => Self::new(Float(self.turn).neg_abs().0),
                 }
             }
 
@@ -130,8 +130,8 @@ macro_rules! impl_angle {
             pub const fn set_direction(&mut self, direction: AngleDirection) {
                 use AngleDirection as D;
                 match direction {
-                    D::CounterClockwise | D::Undefined => self.turn = Float(self.turn).abs().0,
-                    D::Clockwise => self.turn = Float(self.turn).neg_abs().0,
+                    D::Positive | D::Undefined => self.turn = Float(self.turn).abs().0,
+                    D::Negative => self.turn = Float(self.turn).neg_abs().0,
                 }
             }
 

src/num/geom/metric/angle/impl/int.rs

@@ -206,9 +206,9 @@ macro_rules! impl_angle {
                 if self.turn == 0 {
                     D::Undefined
                 } else if self.turn > 0 {
-                    D::CounterClockwise
+                    D::Positive
                 } else {
-                    D::Clockwise
+                    D::Negative
                 }
             }
 
@@ -218,8 +218,8 @@ macro_rules! impl_angle {
             pub const fn with_direction(self, direction: AngleDirection) -> Self {
                 use AngleDirection as D;
                 match direction {
-                    D::CounterClockwise | D::Undefined => Self::new(self.turn.saturating_abs()),
-                    D::Clockwise => Self::new(-self.turn.saturating_abs()),
+                    D::Positive | D::Undefined => Self::new(self.turn.saturating_abs()),
+                    D::Negative => Self::new(-self.turn.saturating_abs()),
                 }
             }
 
@@ -229,8 +229,8 @@ macro_rules! impl_angle {
             pub fn set_direction(&mut self, direction: AngleDirection) {
                 use AngleDirection as D;
                 match direction {
-                    D::CounterClockwise | D::Undefined => self.turn = self.turn.saturating_abs(),
-                    D::Clockwise => self.turn = -self.turn.saturating_abs(),
+                    D::Positive | D::Undefined => self.turn = self.turn.saturating_abs(),
+                    D::Negative => self.turn = -self.turn.saturating_abs(),
                 }
             }
 
@@ -268,22 +268,22 @@ macro_rules! impl_angle {
 
             /// Returns the angle direction.
             ///
-            /// For unsigned integers the direction is always `CounterClockwise`.
-            pub const fn direction(self) -> AngleDirection { AngleDirection::CounterClockwise }
+            /// For unsigned integers the direction is always `Positive`.
+            pub const fn direction(self) -> AngleDirection { AngleDirection::Positive }
 
             /// Returns a version of the angle with the given `direction` (no-op for unsigned).
             ///
-            /// Unsigned integers can only have `CounterClockwise` direction.
+            /// Unsigned integers can only have `Positive` direction.
             pub const fn with_direction(self, _direction: AngleDirection) -> Self { self }
 
             /// Returns a version of the angle with the given `direction` (no-op for unsigned).
             ///
-            /// Unsigned integers can only have `CounterClockwise` direction.
+            /// Unsigned integers can only have `Positive` direction.
             pub const fn set_direction(self, _direction: AngleDirection) {}
 
             /// Returns a version of the angle with inverted direction (no-op for unsigned).
             ///
-            /// Unsigned integers can only have `CounterClockwise` direction.
+            /// Unsigned integers can only have `Positive` direction.
             pub const fn invert_direction(self) -> Self { self }
 
             /// Returns the negative version of the angle (no-op for unsigned).

src/num/geom/metric/angle/impl/test_int.rs

@@ -52,13 +52,13 @@ mod angle_i16 {
     #[test]
     fn signed_angle_direction() {
         let angle = Angle::new(-i16::MAX / 4);
-        assert_eq!(angle.direction(), AngleDirection::Clockwise);
+        assert_eq!(angle.direction(), AngleDirection::Negative);
 
-        let positive_angle = angle.with_direction(AngleDirection::CounterClockwise);
-        assert_eq!(positive_angle.direction(), AngleDirection::CounterClockwise);
+        let positive_angle = angle.with_direction(AngleDirection::Positive);
+        assert_eq!(positive_angle.direction(), AngleDirection::Positive);
 
         let inverted = positive_angle.invert_direction();
-        assert_eq!(inverted.direction(), AngleDirection::Clockwise);
+        assert_eq!(inverted.direction(), AngleDirection::Negative);
     }
 
     /// Test conversion of angle to degrees using integer scaling.
@@ -94,14 +94,14 @@ mod angle_i16 {
     #[test]
     fn angle_set_direction() {
         let mut angle = Angle::<i16>::new(-i16::MAX / 3);
-        assert_eq!(angle.direction(), AngleDirection::Clockwise);
+        assert_eq!(angle.direction(), AngleDirection::Negative);
 
-        angle.set_direction(AngleDirection::CounterClockwise);
-        assert_eq!(angle.direction(), AngleDirection::CounterClockwise);
+        angle.set_direction(AngleDirection::Positive);
+        assert_eq!(angle.direction(), AngleDirection::Positive);
 
         // Undefined should be treated as counterclockwise.
         angle.set_direction(AngleDirection::Undefined);
-        assert_eq!(angle.direction(), AngleDirection::CounterClockwise);
+        assert_eq!(angle.direction(), AngleDirection::Positive);
     }
 }
 
@@ -124,10 +124,10 @@ mod angle_u16 {
     #[test]
     fn unsigned_angle_direction() {
         let unsigned_angle = Angle::<u16>::new(u16::MAX / 4);
-        assert_eq!(unsigned_angle.direction(), AngleDirection::CounterClockwise);
+        assert_eq!(unsigned_angle.direction(), AngleDirection::Positive);
 
         // Setting direction should have no effect.
-        let same_angle = unsigned_angle.with_direction(AngleDirection::Clockwise);
-        assert_eq!(same_angle.direction(), AngleDirection::CounterClockwise);
+        let same_angle = unsigned_angle.with_direction(AngleDirection::Negative);
+        assert_eq!(same_angle.direction(), AngleDirection::Positive);
     }
 }

src/num/geom/metric/angle/kind.rs

@@ -1,11 +1,11 @@
 // devela::num::geom::metric::angle::kind
 //
-//! Definitions related to angles.
+//! Defines [`AngleKind`].
 //
 
 use crate::{ExtFloatConst, Interval};
 
-/// The angle kind, based on its normalized magnitude.
+/// The kind of [`Angle`], based on its normalized turn.
 ///
 /// The variant values are normalized to the full range of an u8.
 #[must_use]

src/num/geom/metric/angle/mod.rs

@@ -69,6 +69,9 @@ pub use kind::AngleKind;
 /// - Kind:
 ///   - [`kind`](Self::kind), *(
 ///     [`is_`](Self::is_kind). )*
+///
+/// This type does **not enforce normalization**, but it is expected
+/// to be normalized in most use cases.
 #[must_use]
 #[repr(transparent)]
 pub struct Angle<T> {
@@ -83,7 +86,7 @@ impl<T> Angle<T> {
     }
 }
 
-/// The angle direction.
+/// The direction of rotation of an angle.
 ///
 /// In mathematics and most graphics programming contexts, the default direction
 /// for angle measurements is counterclockwise from a defined zero point (usually
@@ -97,16 +100,35 @@ impl<T> Angle<T> {
 #[repr(i8)]
 #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum AngleDirection {
-    /// By convention, positive angles represent a counterclockwise rotation.
+    /// By convention, **positive** angles represent a **counterclockwise** rotation.
+    ///
+    /// Also known as the Right-Handed Rule.
     ///
-    /// This is the default direction.
+    /// This is the default direction of rotation.
     #[default]
-    CounterClockwise = 1,
+    Positive = 1,
 
-    /// By convention, negative angles represent a counterclockwise rotation.
-    Clockwise = -1,
+    /// By convention, **negative** angles represent a **clockwise** rotation.
+    ///
+    /// Also known as the Left-Hand Rule.
+    Negative = -1,
 
-    /// An undefined direction can happen when a full turn angle is normalized
-    /// to an unsigned 0, like when using primitive signed integers.
+    /// An undefined direction can occur when a full-turn angle is normalized
+    /// to an unsigned `0`, such as when working with primitive signed integers.
     Undefined = 0,
 }
+
+#[allow(missing_docs, non_upper_case_globals)]
+impl AngleDirection {
+    /// Alias of **positive** angle direction.
+    pub const CounterClockwise: AngleDirection = AngleDirection::Positive;
+    pub const CCW: AngleDirection = AngleDirection::Positive;
+    pub const RightHandRule: AngleDirection = AngleDirection::Positive;
+    pub const RHR: AngleDirection = AngleDirection::Positive;
+
+    /// Alias of **negative** angle direction.
+    pub const Clockwise: AngleDirection = AngleDirection::Negative;
+    pub const CW: AngleDirection = AngleDirection::Negative;
+    pub const LeftHandRule: AngleDirection = AngleDirection::Positive;
+    pub const LHR: AngleDirection = AngleDirection::Positive;
+}