diff --git a/src/capistry/_math.py b/src/capistry/_math.py index f3a5a91..0628aac 100644 --- a/src/capistry/_math.py +++ b/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. diff --git a/src/capistry/cap.py b/src/capistry/cap.py index 7e7ce23..a769e18 100644 --- a/src/capistry/cap.py +++ b/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 ---------- diff --git a/src/capistry/compare.py b/src/capistry/compare.py index 23288e6..df4ff33 100644 --- a/src/capistry/compare.py +++ b/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 ------- diff --git a/src/capistry/fillet.py b/src/capistry/fillet.py index 9e2159e..4553dee 100644 --- a/src/capistry/fillet.py +++ b/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. diff --git a/src/capistry/stem.py b/src/capistry/stem.py index 26c84bf..5da0d23 100644 --- a/src/capistry/stem.py +++ b/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 diff --git a/src/capistry/taper.py b/src/capistry/taper.py index 008bb3d..ec6e922 100644 --- a/src/capistry/taper.py +++ b/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 ---------- diff --git a/src/capistry/utils.py b/src/capistry/utils.py index c5e0a41..06ccc30 100644 --- a/src/capistry/utils.py +++ b/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 -------