From cdeb8053c3aa2510189429d717ab09e70f134716 Mon Sep 17 00:00:00 2001 From: Joseph Heck Date: Fri, 1 Nov 2024 11:31:02 -0700 Subject: [PATCH] cleaning up documentation - resolving warnings, tweaking a few abstracts, matching code updates (#123) --- Package.resolved | 8 ++++---- .../Documentation.docc/Curation/Repo.md | 14 ++++++++------ .../Curation/WebSocketProvider.md | 6 ++++-- .../Curation/WebSocketProviderConfiguration.md | 7 ++++--- .../AutomergeRepo/Networking/NetworkProvider.swift | 2 +- .../Networking/Providers/PeerToPeerProvider.swift | 2 +- .../Networking/Providers/WebSocketProvider.swift | 11 ++++++----- .../Providers/WebSocketProviderConfiguration.swift | 1 + Sources/AutomergeRepo/ShareAuthorizing.swift | 2 +- .../Sync/SyncV1Msg+encode+decode.swift | 5 ----- 10 files changed, 30 insertions(+), 28 deletions(-) diff --git a/Package.resolved b/Package.resolved index bc7d85d..d9aa801 100644 --- a/Package.resolved +++ b/Package.resolved @@ -5,8 +5,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/automerge/automerge-swift", "state" : { - "revision" : "410b1d1b8bec078227dbb4fe8c16e1a4541d01cb", - "version" : "0.5.18" + "revision" : "c8daf47b5cb77ae5eec451a4e4b77ad6f6db8f5e", + "version" : "0.5.19" } }, { @@ -77,8 +77,8 @@ "kind" : "remoteSourceControl", "location" : "https://github.com/apple/swift-distributed-tracing", "state" : { - "revision" : "11c756c5c4d7de0eeed8595695cadd7fa107aa19", - "version" : "1.1.1" + "revision" : "6483d340853a944c96dbcc28b27dd10b6c581703", + "version" : "1.1.2" } }, { diff --git a/Sources/AutomergeRepo/Documentation.docc/Curation/Repo.md b/Sources/AutomergeRepo/Documentation.docc/Curation/Repo.md index 79aeec6..f2b6a80 100644 --- a/Sources/AutomergeRepo/Documentation.docc/Curation/Repo.md +++ b/Sources/AutomergeRepo/Documentation.docc/Curation/Repo.md @@ -13,10 +13,10 @@ When network providers are active, the repository attempts to sync documents wit ### Creating a repository -- ``init(sharePolicy:saveDebounce:)-9tksd`` -- ``init(sharePolicy:saveDebounce:)-8umfb`` -- ``init(sharePolicy:storage:saveDebounce:)`` -- ``init(sharePolicy:storage:networks:saveDebounce:)`` +- ``init(sharePolicy:saveDebounce:maxResolveFetchIterations:resolveFetchIterationDelay:)-3j0z7`` +- ``init(sharePolicy:saveDebounce:maxResolveFetchIterations:resolveFetchIterationDelay:)-18my9`` +- ``init(sharePolicy:storage:saveDebounce:maxResolveFetchIterations:resolveFetchIterationDelay:)`` +- ``init(sharePolicy:storage:networks:saveDebounce:maxResolveFetchIterations:resolveFetchIterationDelay:)`` ### Configuring a repository @@ -29,8 +29,10 @@ When network providers are active, the repository attempts to sync documents wit - ``create()`` - ``create(id:)`` -- ``create(data:id:)`` -- ``create(doc:id:)`` + +### Importing a document + +- ``import(handle:)`` ### Cloning a document diff --git a/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProvider.md b/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProvider.md index 79537f5..2e1377d 100644 --- a/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProvider.md +++ b/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProvider.md @@ -25,7 +25,7 @@ struct MeetingNotesApp: App { } ``` -To connect the repository to a remote endpoint, make an async call to ``connect(to:)``, passing the WebSocket URL: +To connect the repository to a remote endpoint, make an async call to ``connect(to:)-32her``, passing the WebSocket URL: ```swift Button { @@ -44,6 +44,7 @@ Button { - ``init(_:)`` - ``WebSocketProviderConfiguration`` - ``ProviderConfiguration`` +- ``NetworkConnectionEndpoint`` ### Configuring the provider @@ -51,7 +52,8 @@ Button { ### Establishing Connections -- ``connect(to:)`` +- ``connect(to:)-32her`` +- ``connect(to:)-5y82b`` - ``disconnect()`` ### Sending messages diff --git a/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProviderConfiguration.md b/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProviderConfiguration.md index 6265885..a9a8025 100644 --- a/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProviderConfiguration.md +++ b/Sources/AutomergeRepo/Documentation.docc/Curation/WebSocketProviderConfiguration.md @@ -1,4 +1,4 @@ -# ``AutomergeRepo/WebSocketProvider/WebSocketProviderConfiguration`` +# ``AutomergeRepo/WebSocketProviderConfiguration`` ## Topics @@ -8,9 +8,10 @@ ### Creating a configuration -- ``init(_:)`` -- ``init(reconnectOnError:loggingAt:)`` +- ``init(reconnectOnError:loggingAt:maxNumberOfConnectRetries:)`` ### Inspecting a configuration - ``reconnectOnError`` +- ``maxNumberOfConnectRetries`` +- ``logLevel`` diff --git a/Sources/AutomergeRepo/Networking/NetworkProvider.swift b/Sources/AutomergeRepo/Networking/NetworkProvider.swift index 08feffb..aafbfdc 100644 --- a/Sources/AutomergeRepo/Networking/NetworkProvider.swift +++ b/Sources/AutomergeRepo/Networking/NetworkProvider.swift @@ -71,7 +71,7 @@ public protocol NetworkProvider: Sendable { /// Set the delegate for the peer to peer provider. /// - Parameters: /// - delegate: The delegate instance. - /// - peerId: The peer ID to use for the peer to peer provider. + /// - peer: The peer ID to use for the peer to peer provider. /// - metadata: The peer metadata, if any, to use for the peer to peer provider. /// /// This is typically called when the delegate adds the provider, and provides this network diff --git a/Sources/AutomergeRepo/Networking/Providers/PeerToPeerProvider.swift b/Sources/AutomergeRepo/Networking/Providers/PeerToPeerProvider.swift index bc23365..f4b711c 100644 --- a/Sources/AutomergeRepo/Networking/Providers/PeerToPeerProvider.swift +++ b/Sources/AutomergeRepo/Networking/Providers/PeerToPeerProvider.swift @@ -194,7 +194,7 @@ public final class PeerToPeerProvider: NetworkProvider { /// Requests the network transport to send a message. /// - Parameter message: The message to send. - /// - Parameter to: An option peerId to identify the recipient for the message. If nil, the message is sent to all + /// - Parameter peer: An option peerId to identify the recipient for the message. If nil, the message is sent to all /// connected peers. public func send(message: SyncV1Msg, to peer: PEER_ID?) async { if let peerId = peer { diff --git a/Sources/AutomergeRepo/Networking/Providers/WebSocketProvider.swift b/Sources/AutomergeRepo/Networking/Providers/WebSocketProvider.swift index 73f80dd..dcc0b76 100644 --- a/Sources/AutomergeRepo/Networking/Providers/WebSocketProvider.swift +++ b/Sources/AutomergeRepo/Networking/Providers/WebSocketProvider.swift @@ -7,6 +7,7 @@ internal import OSLog /// An Automerge-repo network provider that connects to other repositories using WebSocket. @AutomergeRepo public final class WebSocketProvider: NetworkProvider { + /// The type that represents the endpoint that this provider connects with. public typealias NetworkConnectionEndpoint = URL /// The name of this provider. @@ -50,16 +51,16 @@ public final class WebSocketProvider: NetworkProvider { peered = false } - /// Initiate an outgoing connection. + /// Initiate an outgoing connection to a URL. /// - /// Create a default `URLRequest` and create a WebSocket connection with it. + /// Creates a default `URLRequest` from the `URL` you provide and creates a WebSocket connection with it. public func connect(to url: URL) async throws { try await connect(to: URLRequest(url: url)) } - /// Initiate an outgoing connection. + /// Initiate an outgoing connection to a URL Request. /// - /// Create a WebSocket connection with the provided `URLRequest`. + /// Create a WebSocket connection with the `URLRequest` you provide. public func connect(to request: URLRequest) async throws { if peered { Logger.websocket.error("Attempting to connect while already peered") @@ -150,7 +151,7 @@ public final class WebSocketProvider: NetworkProvider { /// Set the delegate for the peer to peer provider. /// - Parameters: /// - delegate: The delegate instance. - /// - peerId: The peer ID to use for the peer to peer provider. + /// - peer: The peer ID to use for the peer to peer provider. /// - metadata: The peer metadata, if any, to use for the peer to peer provider. /// /// This is typically called when the delegate adds the provider, and provides this network diff --git a/Sources/AutomergeRepo/Networking/Providers/WebSocketProviderConfiguration.swift b/Sources/AutomergeRepo/Networking/Providers/WebSocketProviderConfiguration.swift index a8877cc..d439b00 100644 --- a/Sources/AutomergeRepo/Networking/Providers/WebSocketProviderConfiguration.swift +++ b/Sources/AutomergeRepo/Networking/Providers/WebSocketProviderConfiguration.swift @@ -23,6 +23,7 @@ public struct WebSocketProviderConfiguration: Sendable { /// - Parameter reconnectOnError: A Boolean value that indicates if the provider should attempt to reconnect /// when it fails with an error. /// - Parameter loggingAt: The verbosity of the logs sent to the unified logging system. + /// - Parameter maxNumberOfConnectRetries: The maximum number of reconnections allowed before the WebSocket provider disconnects. If `nil`, the default, retries continue forever. public init(reconnectOnError: Bool, loggingAt: LogVerbosity = .errorOnly, maxNumberOfConnectRetries: Int? = nil) { self.reconnectOnError = reconnectOnError self.maxNumberOfConnectRetries = maxNumberOfConnectRetries diff --git a/Sources/AutomergeRepo/ShareAuthorizing.swift b/Sources/AutomergeRepo/ShareAuthorizing.swift index a0a99e9..6af8a8b 100644 --- a/Sources/AutomergeRepo/ShareAuthorizing.swift +++ b/Sources/AutomergeRepo/ShareAuthorizing.swift @@ -15,7 +15,7 @@ public protocol ShareAuthorizing: Sendable { /// /// If you need a type that supports more state and logic to determine authorization to share, /// initialize a ``Repo`` with your own type that conforms to ``ShareAuthorizing`` with -/// ``Repo/init(sharePolicy:saveDebounce:)-8umfb``. +/// ``Repo/init(sharePolicy:saveDebounce:maxResolveFetchIterations:resolveFetchIterationDelay:)-3j0z7``. public struct SharePolicy: ShareAuthorizing, Sendable { /// Returns a Boolean value that indicates whether a document may be shared. /// - Parameters: diff --git a/Sources/AutomergeRepo/Sync/SyncV1Msg+encode+decode.swift b/Sources/AutomergeRepo/Sync/SyncV1Msg+encode+decode.swift index 68068e8..ccfa18f 100644 --- a/Sources/AutomergeRepo/Sync/SyncV1Msg+encode+decode.swift +++ b/Sources/AutomergeRepo/Sync/SyncV1Msg+encode+decode.swift @@ -33,14 +33,9 @@ public extension SyncV1Msg { /// /// - Parameters: /// - data: The data to decode. - /// - withGossip: A Boolean value that indicates whether to include decoding of handshake messages. - /// - withHandshake: A Boolean value that indicates whether to include decoding of gossip messages. /// - Returns: The decoded message, or ``SyncV1Msg/unknown(_:)`` if the previous decoding attempts failed. /// /// The decoding is ordered from the perspective of an initiating client expecting a response to minimize attempts. - /// Enable `withGossip` to attempt to decode head gossip messages, and `withHandshake` to include handshake phase - /// messages. - /// With both `withGossip` and `withHandshake` set to `true`, the decoding is exhaustive over all V1 messages. static func decode(_ data: Data) -> SyncV1Msg { var cborMsg: CBOR? = nil