documentation updates and swiftformat pass (#194)

Author: heckj

Sources/Automerge/Automerge.docc/Automerge.md

@@ -68,6 +68,7 @@ Read <doc:FiveMinuteQuickstart> to get a quick taste of how to use Automerge, or
 
 - ``Automerge/AutomergeText``
 - ``Automerge/Cursor``
+- ``Automerge/Position``
 - ``Automerge/Mark``
 - ``Automerge/ExpandMark``
 
@@ -111,6 +112,7 @@ Read <doc:FiveMinuteQuickstart> to get a quick taste of how to use Automerge, or
 
 ### Type Conversion Errors
 
+- ``Automerge/ScalarValueConversionError``
 - ``Automerge/BooleanScalarConversionError``
 - ``Automerge/BytesScalarConversionError``
 - ``Automerge/IntScalarConversionError``

Sources/Automerge/Automerge.docc/Curation/Codable/AutomergeEncoder.md

@@ -17,6 +17,9 @@ var myColors = ColorList(colors: ["blue", "red"])
 try encoder.encode(myColors)
 ```
 
+To support cross-platform usage, when provided a optional type to encode, the encoder writes a
+``ScalarValue/Null`` into the Document as opposed to not creating the relevant entry in a map or list.
+
 ## Topics
 
 ### Creating an Encoder

Sources/Automerge/Automerge.docc/Curation/Document.md

@@ -125,6 +125,7 @@
 ### Observing Documents
 
 - ``objectWillChange``
+- ``objectDidChange``
 
 ### Transfering Documents
 

Sources/Automerge/BoundTypes/AutomergeText.swift

@@ -224,7 +224,7 @@ public final class AutomergeText: Codable, @unchecked Sendable {
     /// document.
     /// - Parameters:
     ///   - doc: The Automerge document associated with this reference.
-    ///   - path: A string path that represents a `Text` container within the Automerge document.
+    ///   - id: The Automerge object ID of the text object to bind.
     public func bind(doc: Document, id: ObjId) throws {
         // this assert runs afoul of the encoder, which doesn't make sense right now, but
         // I don't want to second guess it at the moment.

Sources/Automerge/ChangeHash.swift

@@ -12,7 +12,6 @@ public struct ChangeHash: Equatable, Hashable, CustomDebugStringConvertible, Sen
 }
 
 public extension Set<ChangeHash> {
-
     /// Transforms each `ChangeHash` in the set into its byte array (`[UInt8]`). This raw byte representation
     /// captures the state of the document at a specific point in its history, allowing for efficient storage
     /// and retrieval of document states.
@@ -25,16 +24,16 @@ public extension Set<ChangeHash> {
 }
 
 public extension Data {
-
-    /// Interprets the data to return the data as a set of change hashes that represent a state within an Automerge document. If the data is not a multiple of 32 bytes, returns nil.
+    /// Interprets the data to return the data as a set of change hashes that represent a state within an Automerge
+    /// document. If the data is not a multiple of 32 bytes, returns nil.
     func heads() -> Set<ChangeHash>? {
         let rawBytes: [UInt8] = Array(self)
         guard rawBytes.count % 32 == 0 else { return nil }
         let totalHashes = rawBytes.count / 32
-        let heads = (0..<totalHashes).map { index in
+        let heads = (0 ..< totalHashes).map { index in
             let lowerBound = index * 32
             let upperBound = (index + 1) * 32
-            let bytes = rawBytes[lowerBound..<upperBound]
+            let bytes = rawBytes[lowerBound ..< upperBound]
             return ChangeHash(bytes: Array(bytes))
         }
         return Set(heads)

Sources/Automerge/Codable/AnyCodingKey.swift

@@ -67,7 +67,7 @@ extension AnyCodingKey: CodingKey {
     ///
     /// For a non-failable initializer for ``AnyCodingKey``, use ``AnyCodingKey/init(_:)-5azuh``.
     ///
-    /// - Parameter stringVal: The key for a keyed container.
+    /// - Parameter stringValue: The key for a keyed container.
     public init?(stringValue: String) {
         pathElement = Automerge.Prop.Key(stringValue)
     }

Sources/Automerge/Codable/Decoding/AutomergeDecoder.swift

@@ -14,7 +14,7 @@ public struct AutomergeDecoder {
     }
 
     /// Returns the type you specify, decoded from the Automerge document referenced by the decoder.
-    /// - Parameter _: _ The type of the value to decode from the Automerge document.
+    /// - Parameter : The type of the value to decode from the Automerge document.
     @inlinable public func decode<T: Decodable>(_: T.Type) throws -> T {
         if T.self == AutomergeText.self {
             // Special case decoding AutomergeText - when it's the top level type being encoded,
@@ -37,8 +37,8 @@ public struct AutomergeDecoder {
 
     /// Returns the type you specify, decoded from the Automerge document referenced by the decoder.
     /// - Parameters:
-    ///   - _: _ The type of the value to decode from the Automerge document.
-    ///   - path: The path to the schema location within the Automerge document to attempt to decode into the type you
+    ///   - : The type of the value to decode from the Automerge document.
+    ///  - path: The path to the schema location within the Automerge document to attempt to decode into the type you
     /// provide.
     ///
     ///  The `path` parameter accepts any type conforming to the `CodingKey` protocol.

Sources/Automerge/Codable/Decoding/AutomergeSingleValueDecodingContainer.swift

@@ -184,7 +184,6 @@ struct AutomergeSingleValueDecodingContainer: SingleValueDecodingContainer {
                     debugDescription: "Expected to decode \(T.self) from \(value), but it wasn't `.text`."
                 ))
             }
-
         default:
             return try T(from: impl)
         }

Sources/Automerge/Codable/Encoding/AutomergeEncoder.swift

@@ -1,4 +1,4 @@
-/// An encoder that stores types that conform to the codable protocol into an Automerge document.
+/// An encoder that stores types that conform to the Codable protocol into an Automerge document.
 public struct AutomergeEncoder {
     /// The user info dictionary for the encoder.
     public var userInfo: [CodingUserInfoKey: Any] = [:]

Sources/Automerge/Cursor.swift

@@ -33,9 +33,9 @@ public enum Position {
 extension Position {
     func toFfi() -> FfiPosition {
         switch self {
-        case .cursor(let cursor):
+        case let .cursor(cursor):
             return .cursor(position: cursor.bytes)
-        case .index(let index):
+        case let .index(index):
             return .index(position: index)
         }
     }