final cleanup and documentation

Author: bbrk24

Sources/SwiftCrossUI/Path.swift

@@ -229,16 +229,32 @@ public struct Path {
 
     public init() {}
 
+    /// Move the path's current point to the given point.
+    ///
+    /// This does not draw a line segment. For that, see ``addLine(to:)``.
+    ///
+    /// If ``addLine(to:)``, ``addQuadCurve(control:to:)``,
+    /// ``addCubicCurve(control1:control2:to:)``, or
+    /// ``addArc(center:radius:startAngle:endAngle:clockwise:)`` is called on an empty path
+    /// without calling this method first, the start point is implicitly (0, 0).
     public consuming func move(to point: SIMD2<Double>) -> Path {
         actions.append(.moveTo(point))
         return self
     }
 
+    /// Add a line segment from the current point to the given point.
+    ///
+    /// After this, the path's current point will be the endpoint of this line segment.
     public consuming func addLine(to point: SIMD2<Double>) -> Path {
         actions.append(.lineTo(point))
         return self
     }
 
+    /// Add a quadratic Bézier curve to the path.
+    ///
+    /// This creates an order-2 curve starting at the path's current point, bending towards
+    /// `control`, and ending at `endPoint`. After this, the path's current point will be
+    /// `endPoint`.
     public consuming func addQuadCurve(
         control: SIMD2<Double>,
         to endPoint: SIMD2<Double>
@@ -247,6 +263,11 @@ public struct Path {
         return self
     }
 
+    /// Add a cubic Bézier curve to the path.
+    ///
+    /// This creates an order-3 curve starting at the path's current point, bending towards
+    /// `control1` and `control2`, and ending at `endPoint`. After this, the path's current
+    /// point will be `endPoint`.
     public consuming func addCubicCurve(
         control1: SIMD2<Double>,
         control2: SIMD2<Double>,
@@ -267,6 +288,9 @@ public struct Path {
     }
 
     /// Add an arc segment to the path.
+    ///
+    /// After this, the path's current point will be the endpoint implied by `center`, `radius`,
+    /// and `endAngle`.
     /// - Parameters:
     ///   - center: The location of the center of the circle.
     ///   - radius: The radius of the circle.
@@ -297,11 +321,21 @@ public struct Path {
         return self
     }
 
+    /// Apply the given transform to the segments in the path so far.
+    ///
+    /// While this may adjust the path's current point, it does not otherwise affect segments
+    /// that are added to the path after this method call.
     public consuming func applyTransform(_ transform: AffineTransform) -> Path {
         actions.append(.transform(transform))
         return self
     }
 
+    /// Add the entirety of another path as part of this path.
+    ///
+    /// This can be necessary to section off transforms, as transforms applied to `subpath`
+    /// will not affect this path.
+    ///
+    /// The fill rule and preferred stroke style of the subpath are ignored.
     public consuming func addSubpath(_ subpath: Path) -> Path {
         actions.append(.subpath(subpath.actions))
         return self
@@ -316,6 +350,7 @@ public struct Path {
         return self
     }
 
+    /// Set the fill rule for the path.
     public consuming func fillRule(_ rule: FillRule) -> Path {
         fillRule = rule
         return self

Sources/SwiftCrossUI/Views/Shapes/Circle.swift

@@ -14,8 +14,8 @@ public struct Circle: Shape {
             idealSize: SIMD2(x: 10, y: 10),
             idealWidthForProposedHeight: proposal.y,
             idealHeightForProposedWidth: proposal.x,
-            minimumWidth: 1,
-            minimumHeight: 1,
+            minimumWidth: 0,
+            minimumHeight: 0,
             maximumWidth: nil,
             maximumHeight: nil
         )

Sources/SwiftCrossUI/Views/Shapes/RoundedRectangle.swift

@@ -31,7 +31,7 @@ public struct RoundedRectangle: Shape {
     )
 
     // This corresponds to r_{min} in the above Desmos link. This is the minimum ratio of
-    // cornerRadius to half the side length at which the superellipse is ignored. Above this,
+    // cornerRadius to half the side length at which the superellipse is not applicable. Above this,
     // line segments and circular arcs are used.
     private static let rMin = 0.441968022436
 

Sources/SwiftCrossUI/Views/Shapes/Shape.swift

@@ -1,7 +1,39 @@
+/// A 2-D shape that can be drawn as a view.
+///
+/// If no stroke color or fill color is specified, the default is no stroke and a fill of the
+/// current foreground color.
 public protocol Shape: View
 where Content == EmptyView {
     /// Draw the path for this shape.
     ///
+    /// The bounds passed to a shape that is immediately drawn as a view will always have an
+    /// origin of (0, 0). However, you may pass a different bounding box to subpaths. For example,
+    /// this code draws a rectangle in the left half of the bounds and an ellipse in the right half:
+    /// ```swift
+    /// func path(in bounds: Path.Rect) -> Path {
+    ///     Path()
+    ///         .addSubpath(
+    ///             Rectangle().path(
+    ///                 in: Path.Rect(
+    ///                     x: bounds.x,
+    ///                     y: bounds.y,
+    ///                     width: bounds.width / 2.0,
+    ///                     height: bounds.height
+    ///                 )
+    ///             )
+    ///         )
+    ///         .addSubpath(
+    ///             Ellipse().path(
+    ///                 in: Path.Rect(
+    ///                     x: bounds.center.x,
+    ///                     y: bounds.y,
+    ///                     width: bounds.width / 2.0,
+    ///                     height: bounds.height
+    ///                 )
+    ///             )
+    ///         )
+    /// }
+    /// ```
     func path(in bounds: Path.Rect) -> Path
     /// Determine the ideal size of this shape given the proposed bounds.
     ///
@@ -11,7 +43,7 @@ where Content == EmptyView {
     ///   frame the shape will actually be rendered with if the current layout pass is not
     ///   a dry run, while the other properties are used to inform the layout engine how big
     ///   or small the shape can be. The ``ViewSize/idealSize`` property should not vary with
-    ///   the `proposal`, and should only depend on the view's contents. Pass `nil` for the
+    ///   the `proposal`, and should only depend on the shape's contents. Pass `nil` for the
     ///   maximum width/height if the shape has no maximum size (and therefore may occupy
     ///   the entire screen).
     func size(fitting proposal: SIMD2<Int>) -> ViewSize
@@ -24,8 +56,8 @@ extension Shape {
         return ViewSize(
             size: proposal,
             idealSize: SIMD2(x: 10, y: 10),
-            minimumWidth: 1,
-            minimumHeight: 1,
+            minimumWidth: 0,
+            minimumHeight: 0,
             maximumWidth: nil,
             maximumHeight: nil
         )

Sources/SwiftCrossUI/Views/Shapes/StyledShape.swift

@@ -1,3 +1,4 @@
+/// A shape that has style information attached to it, including color and stroke style.
 public protocol StyledShape: Shape {
     var strokeColor: Color? { get }
     var fillColor: Color? { get }