Clean up and fix docstrings

src/capistry/_math.py

@@ -123,7 +123,7 @@ def polygon_height(n, radius, inradius=True):
     radius : float
         The radius value. Interpreted as inradius if `inradius` is True,
         otherwise as circumradius.
-    inradius : bool, optional
+    inradius : bool, default=True
         Whether the given radius is the inradius (True) or
         circumradius (False). Default is True.
 
@@ -165,7 +165,7 @@ def polygon_area(n, radius, inradius=False):
     radius : float
         The radius value. Interpreted as inradius if `inradius` is True,
         otherwise as circumradius.
-    inradius : bool, optional
+    inradius : bool, default=False
         Whether the given radius is the inradius (True) or
         circumradius (False). Default is False.
 
@@ -203,7 +203,7 @@ def polygon_prism_surface(n, radius, height, inradius=False):
         otherwise as circumradius.
     height : float
         Height of the prism.
-    inradius : bool, optional
+    inradius : bool, default=False
         Whether the given radius is the inradius (True) or
         circumradius (False). Default is False.
 

src/capistry/cap.py

@@ -96,23 +96,23 @@ class Cap(Comparable, ABC):
     Parameters
     ----------
     width : float, default=18
-        Width of the keycap in millimeters. Standard keycap width is 18mm.
+        Width of the keycap in millimeters.
     length : float, default=18
-        Length of the keycap in millimeters. Standard keycap length is 18mm.
+        Length of the keycap in millimeters.
     height : float, default=4
-        Total height of the keycap in millimeters. Includes wall thickness.
+        Total height of the keycap in millimeters. Includes roof thickness.
     wall : float, default=1
-        Thickness of the keycap walls in millimeters. Affects structural strength.
+        Thickness of the keycap walls in millimeters.
     roof : float, default=1
-        Thickness of the keycap top surface in millimeters.
+        Thickness of the keycap top surface in millimeters (assuming no surface mapping).
     taper : Taper, default=Taper()
-        Taper configuration for the keycap sides. Controls how sides slope inward.
+        Taper configuration for the keycap sides.
     surface : Surface or None, default=None
-        Optional surface mapping for the keycap top. Adds texture or curvature.
+        Optional surface mapping for the keycap top.
     stem : Stem, default=MXStem()
-        Stem type and configuration for switch attachment. Determines compatibility.
+        Stem which will be attached to the the keycap's body.
     fillet_strategy : FilletStrategy, default=FilletUniform()
-        Strategy for applying fillets to the keycap geometry. Controls edge rounding.
+        Strategy for applying fillets to the keycap geometry.
 
     Attributes
     ----------
@@ -175,7 +175,7 @@ class Cap(Comparable, ABC):
     This is an abstract base class and cannot be instantiated directly.
     Use concrete implementations like RectangularCap, TrapezoidCap, etc.
 
-    The geometry building process is automatic via the __post_init__ method,
+    The geometry building process is triggered automatically in the __post_init__ method,
     but can be manually triggered with the build() method if parameters are changed.
     """
 
@@ -865,9 +865,8 @@ class TrapezoidCap(Cap):
     """
     Keycap with trapezoidal profile.
 
-    A keycap where the top surface is wider than the base, with the width
-    expansion determined by the angle parameter. The trapezoid shape is
-    symmetric, expanding equally on both sides from the base to the top.
+    A symmetric keycap where the top surface is wider than the base, with the width
+    expansion determined by the angle parameter.
 
     Parameters
     ----------

src/capistry/compare.py

@@ -252,7 +252,7 @@ class BaseComparer[T](ABC):
     Abstract base class for all comparers.
 
     Provides the core functionality for comparing multiple objects that
-    implement the Comparable protocol. Builds comparison tables by aligning
+    implement the Comparable ABC. Builds comparison tables by aligning
     metrics across objects and handling missing metrics gracefully.
 
     Parameters
@@ -405,7 +405,7 @@ def _build_table(self) -> tuple[TableSection, ...]:
 
         Constructs the complete comparison table by organizing metrics into
         sections, aligning metrics across objects, and handling missing metrics.
-        Groups are sorted by order value, then alphabetically by title.
+        Groups are sorted by `MetricGroup.order` value, then alphabetically by title.
 
         Returns
         -------

src/capistry/fillet.py

@@ -124,8 +124,8 @@ class FilletStrategy(Comparable, ABC):
     """
     Abstract base class for `capistry.Cap` fillet strategies.
 
-    Defines the interface for applying various types of fillets to keyboard caps
-    including `capistry.MXStem`, `capistry.ChocStem`, and any other `capistry.Cap` subclasses.
+    Defines the interface for applying various types of fillets to caps
+    such as `capistry.TrapezoidCap`, `capistry.RectangularCap`, and any other `capistry.Cap` subclasses.
     Provides common parameters and methods for inner and skirt filleting
     while leaving outer fillet implementation to concrete subclasses.
 

src/capistry/stem.py

@@ -106,7 +106,8 @@ class Stem(Comparable, Compound, ABC):
     operations and 3D geometry representation. All concrete implementations must
     provide a _builder method that defines the specific stem geometry.
 
-    Stems are automatically split at the XY plane to remove excess support material.
+    Stems are automatically split at the XY plane at the end of the  build phase
+    to remove excess support material.
     """
 
     center_at: CenterOf = field(default=CenterOf.GEOMETRY)
@@ -346,9 +347,9 @@ class ChocStem(Stem):
     """
     Concrete implementation of a Kailh Choc V1 compatible keycap stem.
 
-    Creates a specialized stem design for Kailh Choc V1 low-profile switches,
-    featuring dual legs with optional arched profiles and cross-shaped support
-    structures.
+    Stem design compatible with Kailh Choc V1 low-profile switches,
+    featuring dual legs with optional arched profiles and a cross-shaped support
+    structure.
 
     Parameters
     ----------
@@ -367,8 +368,8 @@ class ChocStem(Stem):
         Only used when include_arc is True. Higher values create arcs
         closer to the leg tips.
     arc_width_ratio : float, default=0.25
-        Ratio of leg width for arc sagitta depth (0.0 to 1.0). Controls
-        how pronounced the leg curvature is when arched legs are enabled.
+        Ratio of leg width for arc sagitta depth (0.0 to 1.0). Higher values create
+        arcs with an apex closer to the center of the legs.
     cross_length : float, default=3.7
         Length of the cross support arms (Y-dimension) in millimeters.
     cross_width : float, default=0.45

src/capistry/taper.py

@@ -65,9 +65,6 @@ class Taper(Comparable):
     The Taper class inherits from Comparable, enabling comparison operations
     and integration with metric systems. All transformation methods return
     new instances rather than modifying the original taper in-place.
-
-    Units are not enforced by the class itself - they depend on the application
-    context.
     """
 
     front: float = 0.0
@@ -147,8 +144,7 @@ def clamp(self, min_value: float, max_value: float) -> "Taper":
 
         Constrains each taper value to lie within [min_value, max_value] by
         setting values below `min_value` to `min_value` and values above `max_value`
-        to `max_value`. This is useful for enforcing manufacturing constraints,
-        safety limits, or valid parameter ranges.
+        to `max_value`.
 
         Parameters
         ----------

src/capistry/utils.py

@@ -35,16 +35,15 @@ def spaced_points(
     ----------
     n : int
         Number of points to generate. Must be positive.
-    tolerance : float, optional
-        Minimum distance between any two consecutive points in circular order,
-        by default 0.0
-    start : float, optional
-        Start of the interval (inclusive), by default 0.0
-    end : float, optional
-        End of the interval (exclusive), by default 1.0
-    rand : random.Random or None, optional
+    tolerance : float, default=0.0
+        Minimum distance between any two consecutive points in circular order.
+    start : float, default=0.0
+        Start of the interval (inclusive).
+    end : float, default=1.0
+        End of the interval (exclusive).
+    rand : random.Random or None, default=None
         Random generator instance for reproducible results. If None, uses the
-        default random module, by default None
+        default random module.
 
     Returns
     -------