diff --git a/README.md b/README.md index 898d685..bf8ec4b 100644 --- a/README.md +++ b/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") ), ], ... diff --git a/Sources/CodableDatastore/Datastore/AsyncInstances.swift b/Sources/CodableDatastore/Datastore/AsyncInstances.swift index 26ba40b..4988d21 100644 --- a/Sources/CodableDatastore/Datastore/AsyncInstances.swift +++ b/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,_)`` 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,_)`` 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] { diff --git a/Sources/CodableDatastore/Datastore/Datastore.swift b/Sources/CodableDatastore/Datastore/Datastore.swift index 2c87f25..c5a7ac1 100644 --- a/Sources/CodableDatastore/Datastore/Datastore.swift +++ b/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 diff --git a/Sources/CodableDatastore/Datastore/DatastoreFormat.swift b/Sources/CodableDatastore/Datastore/DatastoreFormat.swift index 869a596..c114e50 100644 --- a/Sources/CodableDatastore/Datastore/DatastoreFormat.swift +++ b/Sources/CodableDatastore/Datastore/DatastoreFormat.swift @@ -87,7 +87,7 @@ public protocol DatastoreFormat: 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. diff --git a/Sources/CodableDatastore/Persistence/DatastoreInterfaceProtocol.swift b/Sources/CodableDatastore/Persistence/DatastoreInterfaceProtocol.swift index da24530..ee33cc2 100644 --- a/Sources/CodableDatastore/Persistence/DatastoreInterfaceProtocol.swift +++ b/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. diff --git a/Sources/CodableDatastore/Persistence/Persistence.swift b/Sources/CodableDatastore/Persistence/Persistence.swift index 2420051..0017ce3 100644 --- a/Sources/CodableDatastore/Persistence/Persistence.swift +++ b/Sources/CodableDatastore/Persistence/Persistence.swift @@ -15,6 +15,7 @@ public protocol Persistence: 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: 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( 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( isolation actor: isolated (any Actor)? = #isolation, actionName: String? = nil,