add code documentation

Author: chloe-yeo

Sources/FoundationEssentials/ProgressManager/ProgressManager.swift

@@ -118,6 +118,8 @@ internal struct AnyMetatypeWrapper: Hashable, Equatable, Sendable {
         }
     }
 
+    
+    /// A `ProgressReporter` instance, used for providing read-only observation of progress updates or composing into other `ProgressManager`s.
     public var reporter: ProgressReporter {
         return .init(manager: self)
     }
@@ -127,6 +129,7 @@ internal struct AnyMetatypeWrapper: Hashable, Equatable, Sendable {
 
         associatedtype Value: Sendable, Hashable, Equatable
 
+        /// The default value to return when property is not set to a specific value.
         static var defaultValue: Value { get }
     }
 
@@ -252,6 +255,9 @@ internal struct AnyMetatypeWrapper: Hashable, Equatable, Sendable {
 
     /// Returns a `Subprogress` representing a portion of `self` which can be passed to any method that reports progress.
     ///
+    /// If the `Subprogress` is not converted into a `ProgressManager` (for example, due to an error or early return),
+    /// then the assigned count is marked as completed in the parent `ProgressManager`.
+    ///
     /// - Parameter count: Units, which is a portion of `totalCount`delegated to an instance of `Subprogress`.
     /// - Returns: A `Subprogress` instance.
     public func subprogress(assigningCount portionOfParent: Int) -> Subprogress {
@@ -264,16 +270,16 @@ internal struct AnyMetatypeWrapper: Hashable, Equatable, Sendable {
     /// Adds a `ProgressReporter` as a child, with its progress representing a portion of `self`'s progress.
     /// - Parameters:
     ///   - reporter: A `ProgressReporter` instance.
-    ///   - portionOfParent: Units, which is a portion of `totalCount`delegated to an instance of `Subprogress`.
-    public func assign(count portionOfParent: Int, to reporter: ProgressReporter) {
+    ///   - count: Units, which is a portion of `totalCount`delegated to an instance of `Subprogress`.
+    public func assign(count: Int, to reporter: ProgressReporter) {
         precondition(isCycle(reporter: reporter) == false, "Creating a cycle is not allowed.")
 
         // get the actual progress from within the reporter, then add as children
         let actualManager = reporter.manager
 
         // Add reporter as child + Add self as parent
         self.addToChildren(childManager: actualManager)
-        actualManager.addParent(parentReporter: self, portionOfParent: portionOfParent)
+        actualManager.addParent(parentReporter: self, portionOfParent: count)
     }
 
     /// Increases `completedCount` by `count`.

Sources/FoundationEssentials/ProgressManager/ProgressReporter.swift

@@ -18,28 +18,40 @@ import Observation
 /// It is read-only and can be added as a child of another ProgressManager.
 @Observable public final class ProgressReporter: Sendable {
 
+    /// The total units of work.
     var totalCount: Int? {
         manager.totalCount
     }
 
+    /// The completed units of work.
+    /// If `self` is indeterminate, the value will be 0.
     var completedCount: Int {
         manager.completedCount
     }
 
+    /// The proportion of work completed.
+    /// This takes into account the fraction completed in its children instances if children are present.
+    /// If `self` is indeterminate, the value will be 0.
     var fractionCompleted: Double {
         manager.fractionCompleted
     }
 
+    /// The state of initialization of `totalCount`.
+    /// If `totalCount` is `nil`, the value will be `true`.
     var isIndeterminate: Bool {
         manager.isIndeterminate
     }
 
+    /// The state of completion of work.
+    /// If `completedCount` >= `totalCount`, the value will be `true`.
     var isFinished: Bool {
         manager.isFinished
     }
 
     /// Reads properties that convey additional information about progress.
-    public func withProperties<T>(_ closure: @Sendable (ProgressManager.Values) throws -> T) rethrows -> T {
+    public func withProperties<T, E: Error>(
+        _ closure: (sending ProgressManager.Values) throws(E) -> sending T
+    ) throws(E) -> T {
         return try manager.getAdditionalProperties(closure)
     }
 

Tests/FoundationEssentialsTests/ProgressManager/ProgressManagerTests.swift

@@ -607,6 +607,16 @@ class TestProgressReporter: XCTestCase {
 
         manager.complete(count: 1)
         XCTAssertEqual(reporter.completedCount, 3)
+        
+        let fileCount = reporter.withProperties { properties in
+            properties.totalFileCount
+        }
+        XCTAssertEqual(fileCount, 0)
+        
+        manager.withProperties { properties in
+            properties.totalFileCount = 6
+        }
+        XCTAssertEqual(reporter.withProperties(\.totalFileCount), 6)
     }
 
     func testAddProgressReporterAsChild() {