Documentation Fixes

README.md

@@ -29,7 +29,7 @@ Please check the [releases](https://github.com/mochidev/CodableDatastore/release
 dependencies: [
     .package(
         url: "https://github.com/mochidev/CodableDatastore.git", 
-        .upToNextMinor(from: "0.4.0")
+        .upToNextMinor(from: "0.5.0")
     ),
 ],
 ...

Sources/CodableDatastore/Datastore/AsyncInstances.swift

@@ -21,7 +21,7 @@ extension AsyncInstances {
     ///
     /// Do not use this method if you need to know if more instances exist past the proposed collection limit, and use a `for try await ... in ...` loop instead to properly handle that case.
     ///
-    /// - Warning: This method is only safe to use from sequences vended by a Datastore ranged ``Datastore/load(range:order:)`` operation as they guarantee that the returned sequence won't stall due to unavailable instances. Do not use it when collecting observations as there is no guarantee observations will be returned!
+    /// - Warning: This method is only safe to use from sequences vended by a Datastore ranged ``Datastore/load(range:order:)-(IndexRangeExpression<IdentifierType>,_)`` operation as they guarantee that the returned sequence won't stall due to unavailable instances. Do not use it when collecting observations as there is no guarantee observations will be returned!
     /// - Parameter collectionLimit: The maximum amount of entries to collect. Specify `.infinity` to _questionably_ collect all instances.
     /// - Returns: An array of instances up to the collection limit.
     public func collectInstances(upTo collectionLimit: Int) async throws -> [Element] {
@@ -39,7 +39,7 @@ extension AsyncInstances {
     ///
     /// Do not use this method if you need to know if more instances exist past the proposed collection limit, and use a `for try await ... in ...` loop instead to properly handle that case.
     ///
-    /// - Warning: This method is only safe to use from sequences vended by a Datastore ranged ``Datastore/load(range:order:)`` operation as they guarantee that the returned sequence won't stall due to unavailable instances. Do not use it when collecting observations as there is no guarantee observations will be returned!
+    /// - Warning: This method is only safe to use from sequences vended by a Datastore ranged ``Datastore/load(range:order:)-(IndexRangeExpression<IdentifierType>,_)`` operation as they guarantee that the returned sequence won't stall due to unavailable instances. Do not use it when collecting observations as there is no guarantee observations will be returned!
     /// - Parameter collectionLimit: The maximum amount of entries to collect. Specify `.infinity` to _questionably_  collect all instances.
     /// - Returns: An array of instances up to the collection limit.
     public func collectInstances(upTo collectionLimit: AsyncInstancesLimit) async throws -> [Element] {

Sources/CodableDatastore/Datastore/Datastore.swift

@@ -627,7 +627,7 @@ extension Datastore {
     /// **[Elided Form]** Load all instances in a datastore as an async sequence.
     ///
     /// - Important: The sequence should be consumed at most a single time, ideally within the same transaction it was created in as it holds a reference to that transaction and thus snapshot of the datastore for data consistency.
-    /// - SeeAlso: This is form that elides the first argument name instead for better completion support, type inference, and indentation. You may however prefer to use ``load(range:order:)-(UnboundedRange,_)`` instead for better completion support, type inference, and indentation.
+    /// - SeeAlso: This is form that elides the first argument name instead for better completion support, type inference, and indentation. You may however prefer to use ``load(range:order:)-(.UnboundedRange,_)`` instead for better completion support, type inference, and indentation.
     /// - Parameters:
     ///   - unboundedRange: The range to load. Specify `...` to load every instance.
     ///   - order: The order to process instances in.
@@ -894,7 +894,7 @@ extension Datastore {
     ///
     /// - Important: The sequence should be consumed at most a single time, ideally within the same transaction it was created in as it holds a reference to that transaction and thus snapshot of the datastore for data consistency.
     /// - Note: If the index is a Many-to-Any type of index, a smaller or larger number of results may be returned here, as some instances may not be respresented in the index, while others are over-represented and may show up multiple times.
-    /// - SeeAlso: This is form that elides the first argument name instead for better completion support, type inference, and indentation. You may however prefer to use ``load(index:range:order:)-(_,UnboundedRange,_)`` instead for better completion support, type inference, and indentation.
+    /// - SeeAlso: This is form that elides the first argument name instead for better completion support, type inference, and indentation. You may however prefer to use ``load(index:range:order:)-(_,.UnboundedRange,_)`` instead for better completion support, type inference, and indentation.
     /// - Parameters:
     ///   - unboundedRange: The range to load. Specify `...` to load every instance.
     ///   - order: The order to process instances in.
@@ -1406,7 +1406,7 @@ extension Datastore where InstanceType: Identifiable, IdentifierType == Instance
 
     /// Observe changes made to an instance with a given identifier.
     ///
-    /// - Parameter identifier: A copy of the instance to observe.
+    /// - Parameter instance: A copy of the instance to observe.
     /// - Returns: An unbounded asynchronous sequence reporting changes to the observed instance.
     @inlinable
     public func observe(
@@ -1418,7 +1418,7 @@ extension Datastore where InstanceType: Identifiable, IdentifierType == Instance
     /// **[Elided Form]** Observe changes made to an instance with a given identifier.
     ///
     /// - SeeAlso: This is form that elides the first argument name instead for better completion support, type inference, and indentation. You may however prefer to use ``observe(instance:)`` instead for better completion support, type inference, and indentation.
-    /// - Parameter identifier: A copy of the instance to observe.
+    /// - Parameter instance: A copy of the instance to observe.
     /// - Returns: An unbounded asynchronous sequence reporting changes to the observed instance.
     @_disfavoredOverload
     @inlinable

Sources/CodableDatastore/Datastore/DatastoreFormat.swift

@@ -87,7 +87,7 @@ public protocol DatastoreFormat<Version, Instance, Identifier>: Sendable {
 
     /// The identifier to be used when de-duplicating instances saved in the persistence.
     ///
-    /// Although ``Instance`` does _not_ need to be ``Identifiable``, a consistent identifier must still be provided for every instance to retrive and persist them. This identifier can be different from `Instance.ID` if truly necessary, though most conformers can simply set it to `Instance.ID`
+    /// Although ``Instance`` does _not_ need to be ``/Swift/Identifiable``, a consistent identifier must still be provided for every instance to retrive and persist them. This identifier can be different from `Instance.ID` if truly necessary, though most conformers can simply set it to `Instance.ID`
     associatedtype Identifier: Indexable & DiscreteIndexable & Sendable
 
     /// A default initializer creating a format instance the datastore can use for evaluation.

Sources/CodableDatastore/Persistence/DatastoreInterfaceProtocol.swift

@@ -25,7 +25,7 @@ public protocol DatastoreInterfaceProtocol: Sendable {
     // MARK: Descriptors
 
     /// Load the descriptor of a ``Datastore``.
-    /// - Parameter datastore: The datastore to query.
+    /// - Parameter datastoreKey: The key of the datastore to query.
     /// - Returns: A descriptor of the datastore as the persistence knows it.
     func datastoreDescriptor(for datastoreKey: DatastoreKey) async throws -> DatastoreDescriptor?
 
@@ -91,7 +91,7 @@ public protocol DatastoreInterfaceProtocol: Sendable {
     ///
     /// - Throws: ``DatastoreInterfaceError/instanceAlreadyExists`` if an instance for the specified identifier already exists.
     /// - Parameters:
-    ///   - indexedValue: The indexed value to search against.
+    ///   - index: The indexed value to search against.
     ///   - identifier: The identifier of an instance to insert.
     ///   - indexName: The name of the direct index to search in.
     ///   - datastoreKey: The key of the datastore the index belongs to.
@@ -107,7 +107,7 @@ public protocol DatastoreInterfaceProtocol: Sendable {
     ///
     /// - Throws: ``DatastoreInterfaceError/instanceNotFound`` if an instance for the specified identifier could not be found.
     /// - Parameters:
-    ///   - indexedValue: The indexed value to search against.
+    ///   - index: The indexed value to search against.
     ///   - identifier: The identifier of the instance to load.
     ///   - indexName: The name of the secondary index to search in.
     ///   - datastoreKey: The key of the datastore the index belongs to.
@@ -123,7 +123,7 @@ public protocol DatastoreInterfaceProtocol: Sendable {
     ///
     /// - Throws: ``DatastoreInterfaceError/instanceAlreadyExists`` if an instance for the specified identifier already exists.
     /// - Parameters:
-    ///   - indexedValue: The indexed value to search against.
+    ///   - index: The indexed value to search against.
     ///   - identifier: The identifier of an instance to insert.
     ///   - indexName: The name of the secondary index to search in.
     ///   - datastoreKey: The key of the datastore the index belongs to.

Sources/CodableDatastore/Persistence/Persistence.swift

@@ -15,6 +15,7 @@ public protocol Persistence<AccessMode>: Sendable {
 
     /// Perform a transaction on the persistence with the specified options.
     /// - Parameters:
+    ///   - actor: The isolation context to run the reciever on.  
     ///   - actionName: The name of the action to use in an undo operation. Only the names of top-level transactions are recorded. We recommend you use the Base localization name here, as you may no longer have the localized version in future versions of your app.
     ///   - options: The options to use while building the transaction.
     ///   - transaction: A closure representing the transaction with which to perform operations on. You should not escape the provided transaction.
@@ -29,6 +30,7 @@ public protocol Persistence<AccessMode>: Sendable {
 extension Persistence {
     /// Perform a transaction on the persistence with the specified options.
     /// - Parameters:
+    ///   - actor: The isolation context to run the reciever on.
     ///   - actionName: The name of the action to use in an undo operation. Only the names of top-level transactions are recorded. We recommend you use the Base localization name here, as you may no longer have the localized version in future versions of your app.
     ///   - options: The options to use while building the transaction.
     ///   - transaction: A closure representing the transaction with which to perform operations on. You should not escape the provided transaction.
@@ -54,10 +56,11 @@ extension Persistence {
     ///
     /// - Warning: Performing changes to a datastore that is not part of the persistence this is called on is unsupported and will result in an error.
     /// - Parameters:
+    ///   - actor: The isolation context to run the reciever on. 
     ///   - actionName: The name of the action to use in an undo operation. Only the names of top-level transactions are recorded. We recommend you use the Base localization name here, as you may no longer have the localized version in future versions of your app.
     ///   - options: A set of options to use when performing the transaction.
     ///   - transaction: A closure with the set of operations to perform. Parameters include a reference to the persistence, and a flag indicating if the transaction is durable.
-    /// - SeeAlso: ``Persistence/perform(actionName:options:transaction:)-1tpvd``   
+    /// - SeeAlso: ``Persistence/perform(isolation:actionName:options:transaction:)-(_,_,_,(Self,Bool)->T)``
     public func perform<T>(
         isolation actor: isolated (any Actor)? = #isolation,
         actionName: String? = nil,
@@ -80,10 +83,11 @@ extension Persistence {
     ///
     /// - Warning: Performing changes to a datastore that is not part of the persistence this is called on is unsupported and will result in an error.
     /// - Parameters:
+    ///   - actor: The isolation context to run the reciever on.
     ///   - actionName: The name of the action to use in an undo operation. Only the names of top-level transactions are recorded.
     ///   - options: A set of options to use when performing the transaction.
     ///   - transaction: A closure with the set of operations to perform.
-    /// - SeeAlso: ``Persistence/perform(actionName:options:transaction:)-5476l``
+    /// - SeeAlso: ``Persistence/perform(isolation:actionName:options:transaction:)-(_,_,_,()->T)``
     public func perform<T>(
         isolation actor: isolated (any Actor)? = #isolation,
         actionName: String? = nil,