cleaning up documentation - resolving warnings, tweaking a few abstra…

…cts, matching code updates (#123)

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"
       }
     },
     {

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
 

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,14 +44,16 @@ Button {
 - ``init(_:)``
 - ``WebSocketProviderConfiguration``
 - ``ProviderConfiguration``
+- ``NetworkConnectionEndpoint``
 
 ### Configuring the provider
 
 - ``setDelegate(_:as:with:)``
 
 ### Establishing Connections
 
-- ``connect(to:)``
+- ``connect(to:)-32her``
+- ``connect(to:)-5y82b``
 - ``disconnect()``
 
 ### Sending messages

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``

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

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 {

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

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

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:

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