Reorder arguments; clarify that addition is scaled, not repeated add

Author: parkera

Proposals/NNNN-calendar-improvements.md

@@ -62,9 +62,9 @@ extension Calendar {
     /// - parameter repeatedTimePolicy: Determines the behavior of the search algorithm when the input produces a time that occurs twice on a particular day.
     /// - parameter direction: Which direction in time to search. The default value is `.forward`, which means later in time.
     @available(FoundationPreview 0.4, *)
-    public func dates(startingAt start: Date,
-                      in range: Range<Date>? = nil,
-                      matching components: DateComponents,
+    public func dates(byMatching components: DateComponents,
+                      startingAt start: Date,
+                      in range: Range<Date>? = nil,                      
                       matchingPolicy: MatchingPolicy = .nextTime,
                       repeatedTimePolicy: RepeatedTimePolicy = .first,
                       direction: SearchDirection = .forward) -> some (Sequence<Date> & Sendable)
@@ -75,7 +75,7 @@ And API on `Calendar` to enumerate addition with a `Sequence`:
 
 ```swift
 extension Calendar {
-    /// Returns a sequence of `Date`s, calculated by repeatedly adding an amount of `Calendar.Component`s to a starting `Date` and then to each subsequent result.
+    /// Returns a sequence of `Date`s, calculated by adding a scaled amount of `Calendar.Component`s to a starting `Date`. 
     /// If a range is supplied, the sequence terminates if the next result is not contained in the range. The starting point does not need to be contained in the range, but if the first result is outside of the range then the result will be an empty sequence.
     ///
     /// - parameter startingAt: The starting point of the search.
@@ -85,13 +85,13 @@ extension Calendar {
     /// - parameter wrappingComponents: If `true`, the component should be incremented and wrap around to zero/one on overflow, and should not cause higher components to be incremented. The default value is `false`.
     /// - returns: A `Sequence` of `Date` values, or an empty sequence if no addition could be performed.
     @available(FoundationPreview 0.4, *)
-    public func dates(startingAt start: Date,
-                      in range: Range<Date>? = nil,
-                      byAdding component: Calendar.Component,
+    public func dates(byAdding component: Calendar.Component,
                       value: Int = 1,
+                      startingAt start: Date,
+                      in range: Range<Date>? = nil,                      
                       wrappingComponents: Bool = false) -> some (Sequence<Date> & Sendable)
 
-    /// Returns a sequence of `Date`s, calculated by repeatedly adding an amount of `Calendar.Component`s to a starting `Date` and then to each subsequent result.
+    /// Returns a sequence of `Date`s, calculated by adding a scaled amount of `Calendar.Component`s to a starting `Date`.
     /// If a range is supplied, the sequence terminates if the next result is not contained in the range. The starting point does not need to be contained in the range, but if the first result is outside of the range then the result will be an empty sequence.
     ///
     /// - parameter startingAt: The starting point of the search.
@@ -100,9 +100,9 @@ extension Calendar {
     /// - parameter wrappingComponents: If `true`, the component should be incremented and wrap around to zero/one on overflow, and should not cause higher components to be incremented. The default value is `false`.
     /// - returns: A `Sequence` of `Date` values, or an empty sequence if no addition could be performed.
     @available(FoundationPreview 0.4, *)
-    public func dates(startingAt start: Date,
-                      in range: Range<Date>? = nil,
-                      byAdding components: DateComponents,
+    public func dates(byAdding components: DateComponents,
+                      startingAt start: Date,
+                      in range: Range<Date>? = nil,                      
                       wrappingComponents: Bool = false) -> some (Sequence<Date> & Sendable)
 }
 ```