update documentation for additional properties methods

Author: chloe-yeo

Sources/FoundationEssentials/ProgressManager/ProgressManager+Properties+Accessors.swift

@@ -382,9 +382,9 @@ extension ProgressManager {
 
         /// Gets or sets custom string properties.
         ///
-        /// This subscript provides read-write access to custom progress properties where both the value
-        /// and summary types are `String`. If the property has not een set, the getter returns the
-        /// property's default value.
+        /// This subscript provides read-write access to custom progress properties where the value
+        /// type is `String?` and the summary type is `[String?]`. If the property has not been set,
+        /// the getter returns the property's default value.
         ///
         /// - Parameter key: A key path to the custom string property type.
         public subscript<P: Property>(dynamicMember key: KeyPath<ProgressManager.Properties, P.Type>) -> String? where P.Value == String?, P.Summary == [String?] {
@@ -403,6 +403,13 @@ extension ProgressManager {
             }
         }
 
+        /// Gets or sets custom URL properties.
+        ///
+        /// This subscript provides read-write access to custom progress properties where the value
+        /// type is `URL?` and the summary type is `[URL?]`. If the property has not been set,
+        /// the getter returns the property's default value.
+        ///
+        /// - Parameter key: A key path to the custom URL property type.
         public subscript<P: Property>(dynamicMember key: KeyPath<ProgressManager.Properties, P.Type>) -> URL? where P.Value == URL?, P.Summary == [URL?] {
             get {
                 return state.propertiesURL[MetatypeWrapper(P.self)] ?? P.self.defaultValue
@@ -419,6 +426,13 @@ extension ProgressManager {
             }
         }
 
+        /// Gets or sets custom UInt64 properties.
+        ///
+        /// This subscript provides read-write access to custom progress properties where the value
+        /// type is `UInt64` and the summary type is `[UInt64]`. If the property has not been set,
+        /// the getter returns the property's default value.
+        ///
+        /// - Parameter key: A key path to the custom UInt64 property type.
         public subscript<P: Property>(dynamicMember key: KeyPath<ProgressManager.Properties, P.Type>) -> UInt64? where P.Value == UInt64, P.Summary == [UInt64] {
             get {
                 return state.propertiesUInt64[MetatypeWrapper(P.self)] ?? P.self.defaultValue
@@ -462,46 +476,62 @@ extension ProgressManager {
 
     // MARK: Methods to Read Additional Properties of Subtree with ProgressManager as root
 
-    /// Returns a summary for the specified integer property across the progress subtree.
+    /// Returns a summary for a custom integer property across the progress subtree.
     ///
     /// This method aggregates the values of a custom integer property from this progress manager
     /// and all its children, returning a consolidated summary value.
     ///
     /// - Parameter property: The type of the integer property to summarize. Must be a property
     ///   where both the value and summary types are `Int`.
-    /// - Returns: The aggregated summary value for the specified property across the entire subtree.
+    /// - Returns: An `Int` summary value for the specified property.
     public func summary<P: Property>(of property: P.Type) -> P.Summary where P.Value == Int, P.Summary == Int {
         return getUpdatedIntSummary(property: MetatypeWrapper(property))
     }
 
-    /// Returns a summary for the specified double property across the progress subtree.
+    /// Returns a summary for a custom double property across the progress subtree.
     ///
     /// This method aggregates the values of a custom double property from this progress manager
     /// and all its children, returning a consolidated summary value.
     ///
     /// - Parameter property: The type of the double property to summarize. Must be a property
     ///   where both the value and summary types are `Double`.
-    /// - Returns: The aggregated summary value for the specified property across the entire subtree.
+    /// - Returns: A `Double` summary value for the specified property.
     public func summary<P: Property>(of property: P.Type) -> P.Summary where P.Value == Double, P.Summary == Double {
         return getUpdatedDoubleSummary(property: MetatypeWrapper(property))
     }
 
-    /// Returns a summary for the specified string property across the progress subtree.
+    /// Returns a summary for a custom string property across the progress subtree.
     ///
     /// This method aggregates the values of a custom string property from this progress manager
     /// and all its children, returning a consolidated summary value.
     ///
     /// - Parameter property: The type of the string property to summarize. Must be a property
-    ///   where both the value and summary types are `String`.
-    /// - Returns: The aggregated summary value for the specified property across the entire subtree.
+    ///   where both the value type is `String?` and the summary type is  `[String?]`.
+    /// - Returns: A `[String?]` summary value for the specified property.
     public func summary<P: Property>(of property: P.Type) -> P.Summary where P.Value == String?, P.Summary == [String?] {
         return getUpdatedStringSummary(property: MetatypeWrapper(property))
     }
 
+    /// Returns a summary for a custom URL property across the progress subtree.
+    ///
+    /// This method aggregates the values of a custom URL property from this progress manager
+    /// and all its children, returning a consolidated summary value as an array of URLs.
+    ///
+    /// - Parameter property: The type of the URL property to summarize. Must be a property
+    ///   where the value type is `URL?` and the summary type is `[URL?]`.
+    /// - Returns: A `[URL?]` summary value for the specified property.
     public func summary<P: Property>(of property: P.Type) -> P.Summary where P.Value == URL?, P.Summary == [URL?] {
         return getUpdatedURLSummary(property: MetatypeWrapper(property))
     }
 
+    /// Returns a summary for a custom UInt64 property across the progress subtree.
+    ///
+    /// This method aggregates the values of a custom UInt64 property from this progress manager
+    /// and all its children, returning a consolidated summary value as an array of UInt64 values.
+    ///
+    /// - Parameter property: The type of the UInt64 property to summarize. Must be a property
+    ///   where the value type is `UInt64` and the summary type is `[UInt64]`.
+    /// - Returns: A `[UInt64]` summary value for the specified property.
     public func summary<P: Property>(of property: P.Type) -> P.Summary where P.Value == UInt64, P.Summary == [UInt64] {
         return getUpdatedUInt64Summary(property: MetatypeWrapper(property))
     }

Sources/FoundationEssentials/ProgressManager/ProgressManager+Properties+Definitions.swift

@@ -13,26 +13,25 @@
 @available(FoundationPreview 6.2, *)
 extension ProgressManager {
 
-    /// A type that conveys task-specific information on progress.
+    /// A type that conveys additional task-specific information on progress.
     ///
     /// The `Property` protocol defines custom properties that can be associated with progress tracking.
-    /// These properties allow you to store and aggregate additional information alongside the standard
-    /// progress metrics like completion counts and file counts.
-    ///
-    /// Properties use a key-value system where the key uniquely identifies the property type,
-    /// and values can be aggregated across progress manager hierarchies through reduction and merging operations.
+    /// These properties allow you to store and aggregate additional information alongside the
+    /// standard progress metrics such as `totalCount` and `completedCount`.
     public protocol Property: SendableMetatype {
 
-        /// The type of individual values stored in this property.
+        /// The type used for individual values of this property.
         ///
-        /// This associated type represents the data type of individual property values
+        /// This associated type represents the type of property values
         /// that can be set on progress managers. Must be `Sendable` and `Equatable`.
+        /// The currently allowed types are `Int`, `Double`, `String?`, `URL?` or `UInt64`.
         associatedtype Value: Sendable, Equatable
 
         /// The type used for aggregated summaries of this property.
         ///
-        /// This associated type represents the data type used when summarizing property values
-        /// across multiple progress managers in a hierarchy. Must be `Sendable` and `Equatable`.
+        /// This associated type represents the type used when summarizing property values
+        /// across multiple progress managers in a subtree.
+        /// The currently allowed types are `Int`, `Double`, `[String?]`, `[URL?]` or `[UInt64]`.
         associatedtype Summary: Sendable, Equatable
 
         /// A unique identifier for this property type.
@@ -54,7 +53,7 @@ extension ProgressManager {
         /// The default summary value for this property type.
         ///
         /// This value is used as the initial summary when no property values have been
-        /// aggregated yet, or as a fallback when summarization fails.
+        /// aggregated yet.
         ///
         /// - Returns: The default summary value for this property type.
         static var defaultSummary: Summary { get }
@@ -80,8 +79,24 @@ extension ProgressManager {
         /// - Returns: A new summary that represents the combination of both input summaries.
         static func merge(_ summary1: Summary, _ summary2: Summary) -> Summary
 
-        /// Determines the behavior for handling childSummary when the child is deinitialized. 
-        static func terminate(_ parentSummary: Summary, _ childSummary: Summary) -> Summary
+        /// Determines how to handle summary data when a progress manager is deinitialized.
+        ///
+        /// This method is used when a progress manager in the hierarchy is being
+        /// deinitialized and its accumulated summary needs to be processed in relation to
+        /// its parent's summary. The behavior can vary depending on the property type:
+        ///
+        /// - For additive properties (like file counts, byte counts): The self summary
+        ///   is typically added to the parent summary to preserve the accumulated progress.
+        /// - For max-based properties (like estimated time remaining): The parent summary
+        ///   is typically preserved as it represents an existing estimate.
+        /// - For collection-based properties (like file URLs): The self summary may be
+        ///   discarded to avoid accumulating stale references.
+        ///
+        /// - Parameters:
+        ///   - parentSummary: The current summary value of the parent progress manager.
+        ///   - selfSummary: The final summary value from the progress manager being deinitialized.
+        /// - Returns: The updated summary that replaces the parent's current summary.
+        static func terminate(_ parentSummary: Summary, _ selfSummary: Summary) -> Summary
     }
 
     // Namespace for properties specific to operations reported on
@@ -109,8 +124,8 @@ extension ProgressManager {
                 return summary1 + summary2
             }
 
-            public static func terminate(_ parentSummary: Int, _ childSummary: Int) -> Int {
-                return parentSummary + childSummary
+            public static func terminate(_ parentSummary: Int, _ selfSummary: Int) -> Int {
+                return parentSummary + selfSummary
             }
         }
 
@@ -136,8 +151,8 @@ extension ProgressManager {
                 return summary1 + summary2
             }
 
-            public static func terminate(_ parentSummary: Int, _ childSummary: Int) -> Int {
-                return parentSummary + childSummary
+            public static func terminate(_ parentSummary: Int, _ selfSummary: Int) -> Int {
+                return parentSummary + selfSummary
             }
         }
 
@@ -163,8 +178,8 @@ extension ProgressManager {
                 return summary1 + summary2
             }
 
-            public static func terminate(_ parentSummary: UInt64, _ childSummary: UInt64) -> UInt64 {
-                return parentSummary + childSummary
+            public static func terminate(_ parentSummary: UInt64, _ selfSummary: UInt64) -> UInt64 {
+                return parentSummary + selfSummary
             }
         }
 
@@ -190,8 +205,8 @@ extension ProgressManager {
                 return summary1 + summary2
             }
 
-            public static func terminate(_ parentSummary: UInt64, _ childSummary: UInt64) -> UInt64 {
-                return parentSummary + childSummary
+            public static func terminate(_ parentSummary: UInt64, _ selfSummary: UInt64) -> UInt64 {
+                return parentSummary + selfSummary
             }
         }
 
@@ -216,8 +231,8 @@ extension ProgressManager {
                 return summary1 + summary2
             }
 
-            public static func terminate(_ parentSummary: [UInt64], _ childSummary: [UInt64]) -> [UInt64] {
-                return parentSummary + childSummary
+            public static func terminate(_ parentSummary: [UInt64], _ selfSummary: [UInt64]) -> [UInt64] {
+                return parentSummary + selfSummary
             }
         }
 
@@ -247,7 +262,7 @@ extension ProgressManager {
                 return max(summary1, summary2)
             }
 
-            public static func terminate(_ parentSummary: Duration, _ childSummary: Duration) -> Duration {
+            public static func terminate(_ parentSummary: Duration, _ selfSummary: Duration) -> Duration {
                 return parentSummary
             }
         }
@@ -278,7 +293,7 @@ extension ProgressManager {
                 return summary1 + summary2
             }
 
-            public static func terminate(_ parentSummary: [URL?], _ childSummary: [URL?]) -> [URL?] {
+            public static func terminate(_ parentSummary: [URL?], _ selfSummary: [URL?]) -> [URL?] {
                 return parentSummary
             }
         }

Sources/FoundationEssentials/ProgressManager/ProgressReporter.swift

@@ -16,7 +16,7 @@ import Observation
 /// ProgressReporter is a wrapper for ProgressManager that carries information about ProgressManager.
 ///
 /// It is read-only and can be added as a child of another ProgressManager.
-@Observable public final class ProgressReporter: Sendable, CustomStringConvertible, CustomDebugStringConvertible {
+@Observable public final class ProgressReporter: Sendable, Hashable, Equatable, CustomStringConvertible, CustomDebugStringConvertible {
 
     /// The total units of work.
     public var totalCount: Int? {
@@ -183,4 +183,12 @@ import Observation
     internal init(manager: ProgressManager) {
         self.manager = manager
     }
+    
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(ObjectIdentifier(self))
+    }
+    
+    public static func == (lhs: ProgressReporter, rhs: ProgressReporter) -> Bool {
+        ObjectIdentifier(lhs) == ObjectIdentifier(rhs)
+    }
 }