Merge pull request rarestype#126 from rarestype/add-doccomments

[patch]: add doccomments, and a special case of `&`

Author: tayloraswift

Sources/JQ/JSON.ArrayAccessor.swift

@@ -29,27 +29,61 @@ extension JSON.ArrayAccessor {
     }
 }
 extension JSON.ArrayAccessor {
+    /// Modify an existing array at the accessed path, returning nil if no such array exists, or
+    /// if the accessed path is invalid.
     @discardableResult
     @inlinable public static func &? <E, T>(
         self: inout Self,
         yield: (inout JSON.Array) throws(E) -> T
     ) throws(E) -> T? {
+        if case .occupied(var array) = self.state {
+            self.state = .writable
+            defer {
+                self.state = .occupied(array)
+            }
+            return try yield(&array)
+        } else {
+            return nil
+        }
+    }
+
+    /// Modify the array at the accessed path, creating an empty array in the tree if it does
+    /// not exist.
+    ///
+    /// Use this when you are confident that the array must be written, and expect to receive
+    /// an error if incompatible data already exists in the accessed location.
+    @inlinable public static func & (
+        self: inout Self,
+        yield: (inout JSON.Array) throws -> ()
+    ) throws {
         switch self.state {
         case .protected:
-            return nil
-        case .reserved:
-            return nil
+            throw JSON.NodeAccessError.protected(self.crumb)
+
+        case .reserved(let offender):
+            throw JSON.NodeAccessError.reserved(self.crumb, offender)
+
         case .writable:
-            return nil
-        case .occupied(var array):
+            var array: JSON.Array = []
+            try yield(&array)
+            self.state = .occupied(array)
+
+        case .occupied(let value):
+            var array: JSON.Array = consume value
             self.state = .writable
             defer {
                 self.state = .occupied(array)
             }
-            return try yield(&array)
+            try yield(&array)
         }
     }
 
+    /// Modify the array at the accessed path, allowing the closure to create, update, or delete
+    /// it. Assigning a value to a node that was originally nil creates it, likewise,
+    /// assigning nil to a node that was originally non-nil deletes it.
+    ///
+    /// If the accessed path is not writable, and the node is assigned a value in the
+    /// closure — even an empty array — a ``NodeAccessError`` is thrown.
     @inlinable public static func & (
         self: inout Self,
         yield: (inout JSON.Array?) throws -> ()
@@ -70,7 +104,7 @@ extension JSON.ArrayAccessor {
             }
 
         case .writable:
-            var array: JSON.Array? = []
+            var array: JSON.Array? = nil
             try yield(&array)
             if  let array: JSON.Array {
                 self.state = .occupied(array)

Sources/JQ/JSON.NodeAccessor.swift

@@ -160,6 +160,8 @@ extension JSON.NodeAccessor {
     }
 }
 extension JSON.NodeAccessor {
+    /// Delete the node at the accessed path, throwing a ``NodeAccessError`` if the location is
+    /// not writable and data already exists there.
     @inlinable public static func &= (
         self: inout Self,
         delete: Never?
@@ -175,6 +177,8 @@ extension JSON.NodeAccessor {
             self.state = .writable
         }
     }
+    /// Create or update the node at the accessed path, throwing a ``NodeAccessError`` if the
+    /// location is not writable.
     @inlinable public static func &= (
         self: inout Self,
         value: consuming JSON.Node
@@ -191,27 +195,59 @@ extension JSON.NodeAccessor {
         }
     }
 
+    /// Modify an existing node at the accessed path, returning nil if no such node exists, or
+    /// if the accessed path is invalid.
     @discardableResult
     @inlinable public static func &? <E, T>(
         self: inout Self,
         yield: (inout JSON.Node) throws(E) -> T
     ) throws(E) -> T? {
+        if case .occupied(var value) = self.state {
+            self.state = .writable
+            defer {
+                self.state = .occupied(value)
+            }
+            return try yield(&value)
+        } else {
+            return nil
+        }
+    }
+
+    /// Modify the node at the accessed path, creating it with a default value of
+    /// ``JSON.Node/null``, if it does not exist.
+    ///
+    /// Use this when you are confident that the node must be written, and expect to receive
+    /// an error if incompatible data already exists in the accessed location.
+    @inlinable public static func & (
+        self: inout Self,
+        yield: (inout JSON.Node) throws -> ()
+    ) throws {
         switch self.state {
         case .protected:
-            return nil
-        case .reserved:
-            return nil
+            throw JSON.NodeAccessError.protected(self.crumb)
+        case .reserved(let offender):
+            throw JSON.NodeAccessError.reserved(self.crumb, offender)
         case .writable:
-            return nil
-        case .occupied(var value):
+            var value: JSON.Node = .null
+            try yield(&value)
+            self.state = .occupied(value)
+
+        case .occupied(let value):
+            var value: JSON.Node = consume value
             self.state = .writable
             defer {
                 self.state = .occupied(value)
             }
-            return try yield(&value)
+            try yield(&value)
         }
     }
 
+    /// Modify the node at the accessed path, allowing the closure to create, update, or delete
+    /// it. Assigning a value to a node that was originally nil creates it, likewise,
+    /// assigning nil to a node that was originally non-nil deletes it.
+    ///
+    /// If the accessed path is not writable, and the node is assigned a value in the
+    /// closure — including an explicit ``JSON.Node/null`` — a ``NodeAccessError`` is thrown.
     @inlinable public static func & (
         self: inout Self,
         yield: (inout JSON.Node?) throws -> ()