Additional documents for CollectSample and HealthKitConstraint (#18)

# Additional documents for CollectSample and HealthKitConstraint

## ♻️ Current situation & Problem
When working with this package for our PICS application, I found it a
bit confusing about the `add` and `remove` functions in the
`HealthKitConstraint` as I misunderstood them to be adding/removing
health kit samples to/from the data sources instead of our application.
Also, when using `CollectSample`, I spent some time finding how to
filter the health kit query to collect data within the specific time
range. I thought that this package did not support such filtering until
I looked into the codes and realized that I could also input the
predicate to it. I also found that the documentation mentioned the
predicate initializations for `CollectSample` only after I found the
predicate parameter in the codes, and would appreciate that if it could
be mentioned more clearly.

I think adding more documentation and code examples for clarification
will possibly not benefit those who are familiar with Swift
documentation or HealthKit packages, but might help users who are new to
Swift to get on board with this package more easily.

## ⚙️ Release Notes 
- Added a code example including predicates for CollectSample
- Clarify the add and remove functions for HealthKitConstraint

## 📚 Documentation
Only additional documents were added were added in this PR.

## ✅ Testing
Only additional documents were added and no codes were changed. Also
checked and verified the changes in the documentation by building
documentation locally.

## 📝 Code of Conduct & Contributing Guidelines 

By submitting creating this pull request, you agree to follow our [Code
of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md):
- [x] I agree to follow the [Code of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md).

README.md

@@ -34,12 +34,15 @@ You need to add the Spezi HealthKit Swift package to
 ### Example
 
 Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data.
+The [`add(sample:)`](https://swiftpackageindex.com/stanfordspezi/spezihealthkit/documentation/spezihealthkit/healthkitconstraint/add(sample:)) function is triggered once for every newly collected HealthKit sample, and the [`remove(sample:)`](https://swiftpackageindex.com/stanfordspezi/spezihealthkit/documentation/spezihealthkit/healthkitconstraint/remove(sample:)) function
 ```swift
 actor ExampleStandard: Standard, HealthKitConstraint {
+    // Add the newly collected HKSample to your application.
     func add(sample: HKSample) async {
         // ...
     }
 
+    // Remove the deleted HKSample from your application.
     func remove(sample: HKDeletedObject) {
         // ...
     }

Sources/SpeziHealthKit/CollectSample/CollectSample.swift

@@ -11,6 +11,38 @@ import Spezi
 
 
 /// Collects a specified `HKSampleType`  in the ``HealthKit`` module.
+///
+/// This structure define what and how the ``HealthKit`` samples are collected. By default, all samples of the provided `HKSampleType` will be collected. The collection starts on calling ``HealthKit/triggerDataSourceCollection()`` if you configure the `deliverySetting` as    ``HealthKitDeliverySetting/manual(safeAnchor:)`` or automatic once the application is launched when you configure anything else than manual, i.e.  ``HealthKitDeliverySetting/anchorQuery(_:saveAnchor:)`` or ``HealthKitDeliverySetting/background(_:saveAnchor:)``.
+///
+/// Your can filter the HealthKit samples to collect by specifying the `predicate`. For example, you can define an  `NSPredicate` to only collect the data collected at a time within the given start and end date. Below is an example to create a `NSPredicate` restricting the data collected in the previous month.
+/// ```swift
+/// private var predicateOneMonth: NSPredicate {
+///     // Define the start and end time for the predicate. In this example,
+///     // we want to collect the samples in the previous month.
+///     let calendar = Calendar(identifier: .gregorian)
+///     let today = calendar.startOfDay(for: Date())
+///     // We want the end date to be tomorrow so that we can collect all the samples today.
+///     guard let endDate = calendar.date(byAdding: .day, value: 1, to: today) else {
+///         fatalError("*** Unable to calculate the end time ***")
+///     }
+///     // Define the start date to one month before.
+///     guard let startDate = calendar.date(byAdding: .month, value: -1, to: today) else {
+///         fatalError("*** Unable to calculate the start time ***")
+///     }
+///     // Initialize the NSPredicate with our start and end dates.
+///     return HKQuery.predicateForSamples(withStart: startDate, end: endDate)
+/// }
+/// ```
+///
+/// Then, you just need to configure `predicate` with the  `predicateOneMonth` you defined as above during your initialization of ``CollectSample`` to only collect data samples in the previous month.
+///
+/// ```swift
+/// CollectSample(
+///     HKQuantityType(.stepCount),
+///     predicate: predicateOneMonth,
+///     deliverySetting: .background(.afterAuthorizationAndApplicationWillLaunch)
+/// )
+/// ```
 public struct CollectSample: HealthKitDataSourceDescription {
     private let collectSamples: CollectSamples
 

Sources/SpeziHealthKit/HealthKit.swift

@@ -16,12 +16,15 @@ import SwiftUI
 /// The `HealthKit` module simplifies access to HealthKit samples ranging from single, anchored, and background queries.
 ///
 /// Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data.
+/// The ``HealthKitConstraint/add(sample:)`` function is triggered once for every newly collected HealthKit sample, and the ``HealthKitConstraint/remove(sample:)`` function is triggered once for every deleted HealthKit sample.
 /// ```swift
 /// actor ExampleStandard: Standard, HealthKitConstraint {
+///    // Add the newly collected HKSample to your application.
 ///    func add(sample: HKSample) async {
 ///        ...
 ///    }
-///
+///  
+///    // Remove the deleted HKSample from your application.
 ///    func remove(sample: HKDeletedObject) {
 ///        ...
 ///    }

Sources/SpeziHealthKit/HealthKitConstraint.swift

@@ -15,12 +15,15 @@ import Spezi
 ///
 /// Make sure that your standard in your Spezi Application conforms to the ``HealthKitConstraint``
 /// protocol to receive HealthKit data.
+/// The ``HealthKitConstraint/add(sample:)`` function is triggered once for every newly collected HealthKit sample, and the ``HealthKitConstraint/remove(sample:)`` function is triggered once for every deleted HealthKit sample.
 /// ```swift
 /// actor ExampleStandard: Standard, HealthKitConstraint {
+///    // Add the newly collected HKSample to your application.
 ///    func add(sample: HKSample) async {
 ///        ...
 ///    }
-///
+///  
+///    // Remove the deleted HKSample from your application.
 ///    func remove(sample: HKDeletedObject) {
 ///        ...
 ///    }

Sources/SpeziHealthKit/SpeziHealthKit.docc/SpeziHealthKit.md

@@ -27,13 +27,15 @@ You need to add the Spezi HealthKit Swift package to
 
 ### Example
 
-Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data.
+Before you configure the ``HealthKit`` module, make sure your `Standard` in your Spezi Application conforms to the ``HealthKitConstraint`` protocol to receive HealthKit data. The ``HealthKitConstraint/add(sample:)`` function is triggered once for every newly collected HealthKit sample, and the ``HealthKitConstraint/remove(sample:)`` function is triggered once for every deleted HealthKit sample.
 ```swift
 actor ExampleStandard: Standard, HealthKitConstraint {
+    // Add the newly collected HKSample to your application.
     func add(sample: HKSample) async {
         // ...
     }
 
+    // Remove the deleted HKSample from your application.
     func remove(sample: HKDeletedObject) {
         // ...
     }