Add more code documentation

christophhagen · Apr 3, 2024 · c19e0e1 · c19e0e1
1 parent a5c1841
commit c19e0e1
Show file tree

Hide file tree

Showing 11 changed files with 213 additions and 4 deletions.
diff --git a/Sources/BinaryCodable/Decoding/CorruptedDataError.swift b/Sources/BinaryCodable/Decoding/CorruptedDataError.swift
@@ -1,8 +1,15 @@
 import Foundation
 
-struct CorruptedDataError: Error {
-
-    let description: String
+/**
+ An error which occurs when the data to decode is in an incorrect format.
+ 
+ This error is used internally during decoding, and should not occur when using ``BinaryDecoder``, ``BinaryStreamDecoder`` or ``BinaryFileDecoder``.
+ It is only relevant when directly using the decoding initializers for ``FixedSizeDecodable``, ``VariableLengthDecodable``,  or ``ZigZagDecodable``.
+ */
+public struct CorruptedDataError: Error {
+
+    /// A textual description of the error
+    public let description: String
 
     init(invalidSize size: Int, for type: String) {
         self.description = "Invalid size \(size) for type \(type)"

diff --git a/Sources/BinaryCodable/Primitives/Bool+Coding.swift b/Sources/BinaryCodable/Primitives/Bool+Coding.swift
@@ -2,13 +2,19 @@ import Foundation
 
 extension Bool: EncodablePrimitive {
 
+    /// The boolean encoded as data
     var encodedData: Data {
         Data([self ? 1 : 0])
     }
 }
 
 extension Bool: DecodablePrimitive {
 
+    /**
+     Decode a boolean from encoded data.
+     - Parameter data: The data to decode
+     - Throws: ``CorruptedDataError``
+     */
     init(data: Data) throws {
         guard data.count == 1 else {
             throw CorruptedDataError(invalidSize: data.count, for: "Bool")

diff --git a/Sources/BinaryCodable/Primitives/Int+Coding.swift b/Sources/BinaryCodable/Primitives/Int+Coding.swift
@@ -8,6 +8,11 @@ extension Int: EncodablePrimitive {
 
 extension Int: DecodablePrimitive {
 
+    /**
+     Decode an integer from zig-zag encoded data.
+     - Parameter data: The data of the zig-zag encoded value.
+     - Throws: ``CorruptedDataError``
+     */
     init(data: Data) throws {
         try self.init(fromZigZag: data)
     }
@@ -17,13 +22,19 @@ extension Int: DecodablePrimitive {
 
 extension Int: ZigZagEncodable {
 
+    /// The integer encoded using zig-zag encoding
     public var zigZagEncoded: Data {
         Int64(self).zigZagEncoded
     }
 }
 
 extension Int: ZigZagDecodable {
 
+    /**
+     Decode an integer from zig-zag encoded data.
+     - Parameter data: The data of the zig-zag encoded value.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromZigZag data: Data) throws {
         let raw = try Int64(data: data)
         guard let value = Int(exactly: raw) else {
@@ -35,6 +46,11 @@ extension Int: ZigZagDecodable {
 
 extension ZigZagEncoded where WrappedValue == Int {
 
+    /**
+     Wrap an integer to enforce zig-zag encoding.
+     - Parameter wrappedValue: The value to wrap
+     - Note: `Int` is already encoded using zig-zag encoding, so wrapping it in `ZigZagEncoded` does nothing.
+     */
     @available(*, deprecated, message: "Property wrapper @ZigZagEncoded has no effect on type Int")
     public init(wrappedValue: Int) {
         self.wrappedValue = wrappedValue
@@ -53,6 +69,11 @@ extension Int: VariableLengthEncodable {
 
 extension Int: VariableLengthDecodable {
 
+    /**
+     Create an integer from variable-length encoded data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromVarint data: Data) throws {
         let intValue = try Int64(fromVarint: data)
         guard let value = Int(exactly: intValue) else {
@@ -66,13 +87,19 @@ extension Int: VariableLengthDecodable {
 
 extension Int: FixedSizeEncodable {
 
+    /// The value encoded as fixed-size data
     public var fixedSizeEncoded: Data {
         Int64(self).fixedSizeEncoded
     }
 }
 
 extension Int: FixedSizeDecodable {
 
+    /**
+     Decode a value from fixed-size data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromFixedSize data: Data) throws {
         let signed = try Int64(fromFixedSize: data)
         guard let value = Int(exactly: signed) else {

diff --git a/Sources/BinaryCodable/Primitives/Int16+Coding.swift b/Sources/BinaryCodable/Primitives/Int16+Coding.swift
@@ -7,6 +7,11 @@ extension Int16: EncodablePrimitive {
 
 extension Int16: DecodablePrimitive {
 
+    /**
+     Decode a value from fixed-size data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     init(data: Data) throws {
         try self.init(fromFixedSize: data)
     }
@@ -16,13 +21,19 @@ extension Int16: DecodablePrimitive {
 
 extension Int16: FixedSizeEncodable {
 
+    /// The value encoded as fixed-size data
     public var fixedSizeEncoded: Data {
         .init(underlying: UInt16(bitPattern: self).littleEndian)
     }
 }
 
 extension Int16: FixedSizeDecodable {
 
+    /**
+     Decode a value from fixed-size data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromFixedSize data: Data) throws {
         guard data.count == MemoryLayout<UInt16>.size else {
             throw CorruptedDataError(invalidSize: data.count, for: "Int16")
@@ -34,6 +45,11 @@ extension Int16: FixedSizeDecodable {
 
 extension FixedSizeEncoded where WrappedValue == Int16 {
 
+    /**
+     Wrap an integer to enforce fixed-size encoding.
+     - Parameter wrappedValue: The value to wrap
+     - Note: `Int16` is already encoded using fixed-size encoding, so wrapping it in `FixedSizeEncoded` does nothing.
+     */
     @available(*, deprecated, message: "Property wrapper @FixedSizeEncoded has no effect on type Int16")
     public init(wrappedValue: Int16) {
         self.wrappedValue = wrappedValue
@@ -51,6 +67,11 @@ extension Int16: VariableLengthEncodable {
 
 extension Int16: VariableLengthDecodable {
 
+    /**
+     Create an integer from variable-length encoded data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromVarint data: Data) throws {
         let value = try UInt16(fromVarint: data)
         self = Int16(bitPattern: value)
@@ -61,13 +82,19 @@ extension Int16: VariableLengthDecodable {
 
 extension Int16: ZigZagEncodable {
 
+    /// The integer encoded using zig-zag encoding
     public var zigZagEncoded: Data {
         Int64(self).zigZagEncoded
     }
 }
 
 extension Int16: ZigZagDecodable {
 
+    /**
+     Decode an integer from zig-zag encoded data.
+     - Parameter data: The data of the zig-zag encoded value.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromZigZag data: Data) throws {
         let raw = try Int64(fromZigZag: data)
         guard let value = Int16(exactly: raw) else {

diff --git a/Sources/BinaryCodable/Primitives/Int32+Coding.swift b/Sources/BinaryCodable/Primitives/Int32+Coding.swift
@@ -8,6 +8,11 @@ extension Int32: EncodablePrimitive {
 
 extension Int32: DecodablePrimitive {
 
+    /**
+     Decode an integer from zig-zag encoded data.
+     - Parameter data: The data of the zig-zag encoded value.
+     - Throws: ``CorruptedDataError``
+     */
     init(data: Data) throws {
         try self.init(fromZigZag: data)
     }
@@ -17,13 +22,19 @@ extension Int32: DecodablePrimitive {
 
 extension Int32: ZigZagEncodable {
 
+    /// The integer encoded using zig-zag encoding
     public var zigZagEncoded: Data {
         Int64(self).zigZagEncoded
     }
 }
 
 extension Int32: ZigZagDecodable {
 
+    /**
+     Decode an integer from zig-zag encoded data.
+     - Parameter data: The data of the zig-zag encoded value.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromZigZag data: Data) throws {
         let raw = try Int64(fromZigZag: data)
         guard let value = Int32(exactly: raw) else {
@@ -35,6 +46,11 @@ extension Int32: ZigZagDecodable {
 
 extension ZigZagEncoded where WrappedValue == Int32 {
 
+    /**
+     Wrap an integer to enforce zig-zag encoding.
+     - Parameter wrappedValue: The value to wrap
+     - Note: `Int32` is already encoded using zig-zag encoding, so wrapping it in `ZigZagEncoded` does nothing.
+     */
     @available(*, deprecated, message: "Property wrapper @ZigZagEncoded has no effect on type Int32")
     public init(wrappedValue: Int32) {
         self.wrappedValue = wrappedValue
@@ -53,6 +69,11 @@ extension Int32: VariableLengthEncodable {
 
 extension Int32: VariableLengthDecodable {
 
+    /**
+     Create an integer from variable-length encoded data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromVarint data: Data) throws {
         let value = try UInt32(fromVarint: data)
         self = Int32(bitPattern: value)
@@ -63,6 +84,7 @@ extension Int32: VariableLengthDecodable {
 
 extension Int32: FixedSizeEncodable {
 
+    /// The value encoded as fixed-size data
     public var fixedSizeEncoded: Data {
         let value = UInt32(bitPattern: littleEndian)
         return Data(underlying: value)
@@ -71,6 +93,11 @@ extension Int32: FixedSizeEncodable {
 
 extension Int32: FixedSizeDecodable {
 
+    /**
+     Decode a value from fixed-size data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromFixedSize data: Data) throws {
         guard data.count == MemoryLayout<UInt32>.size else {
             throw CorruptedDataError(invalidSize: data.count, for: "Int32")

diff --git a/Sources/BinaryCodable/Primitives/Int64+Coding.swift b/Sources/BinaryCodable/Primitives/Int64+Coding.swift
@@ -8,6 +8,11 @@ extension Int64: EncodablePrimitive {
 
 extension Int64: DecodablePrimitive {
 
+    /**
+     Decode an integer from zig-zag encoded data.
+     - Parameter data: The data of the zig-zag encoded value.
+     - Throws: ``CorruptedDataError``
+     */
     init(data: Data) throws {
         try self.init(fromZigZag: data)
     }
@@ -17,6 +22,7 @@ extension Int64: DecodablePrimitive {
 
 extension Int64: ZigZagEncodable {
 
+    /// The integer encoded using zig-zag encoding
     public var zigZagEncoded: Data {
         guard self < 0 else {
             return (UInt64(self.magnitude) << 1).variableLengthEncoding
@@ -26,7 +32,12 @@ extension Int64: ZigZagEncodable {
 }
 
 extension Int64: ZigZagDecodable {
-
+
+    /**
+     Decode an integer from zig-zag encoded data.
+     - Parameter data: The data of the zig-zag encoded value.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromZigZag data: Data) throws {
         let unsigned = try UInt64(fromVarint: data)
 
@@ -43,6 +54,11 @@ extension Int64: ZigZagDecodable {
 
 extension ZigZagEncoded where WrappedValue == Int64 {
 
+    /**
+     Wrap an integer to enforce zig-zag encoding.
+     - Parameter wrappedValue: The value to wrap
+     - Note: `Int64` is already encoded using zig-zag encoding, so wrapping it in `ZigZagEncoded` does nothing.
+     */
     @available(*, deprecated, message: "Property wrapper @ZigZagEncoded has no effect on type Int64")
     public init(wrappedValue: Int64) {
         self.wrappedValue = wrappedValue
@@ -62,6 +78,11 @@ extension Int64: VariableLengthEncodable {
 
 extension Int64: VariableLengthDecodable {
 
+    /**
+     Create an integer from variable-length encoded data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromVarint data: Data) throws {
         let value = try UInt64(fromVarint: data)
         self = Int64(bitPattern: value)
@@ -72,6 +93,7 @@ extension Int64: VariableLengthDecodable {
 
 extension Int64: FixedSizeEncodable {
 
+    /// The value encoded as fixed-size data
     public var fixedSizeEncoded: Data {
         let value = UInt64(bitPattern: littleEndian)
         return Data.init(underlying: value)
@@ -80,6 +102,11 @@ extension Int64: FixedSizeEncodable {
 
 extension Int64: FixedSizeDecodable {
 
+    /**
+     Decode a value from fixed-size data.
+     - Parameter data: The data to decode.
+     - Throws: ``CorruptedDataError``
+     */
     public init(fromFixedSize data: Data) throws {
         guard data.count == MemoryLayout<UInt64>.size else {
             throw CorruptedDataError(invalidSize: data.count, for: "Int64")