More documentation.

YubiKit/YubiKit/APDU.swift

@@ -14,21 +14,8 @@
 
 import Foundation
 
-/*
-@param cla
-   The instruction class.
-@param ins
-   The instruction number.
-@param p1
-   The first instruction paramater byte.
-@param p2
-   The second instruction paramater byte.
-@param data
-   The command data.
-@param type
-   The type of the APDU, short or extended.
-*/
 
+/// Data model for encapsulating an APDU command, as defined by the ISO/IEC 7816-4 standard.
 public struct APDU {
 
     public enum ApduType {
@@ -43,7 +30,15 @@ public struct APDU {
     private let command: Data?
     private let type: ApduType
 
-    init(cla: UInt8, ins: UInt8, p1: UInt8, p2: UInt8, command: Data? = nil, type: ApduType = .short) {
+    /// Creates an APDU struct.
+    /// - Parameters:
+    ///   - cla: The instruction class.
+    ///   - ins: The instruction code.
+    ///   - p1: The first instruction paramater byte.
+    ///   - p2: The second instruction paramater byte.
+    ///   - command: The command data.
+    ///   - type: The type of the APDU, short or extended.
+    public init(cla: UInt8, ins: UInt8, p1: UInt8, p2: UInt8, command: Data? = nil, type: ApduType = .short) {
         self.cla = cla
         self.ins = ins
         self.p1 = p1

YubiKit/YubiKit/Connection.swift

@@ -22,7 +22,7 @@ import Foundation
 
 public protocol Connection: AnyObject {
 
-    /// Create a new Connection
+    /// Create a new Connection to the YubiKey.
     ///
     /// Call this method to get a connection to a YubiKey. The method will wait
     /// until a connection to a YubiKey has been established and then return it.
@@ -33,21 +33,27 @@ public protocol Connection: AnyObject {
     /// If a connection has been established and this method is called again the
     /// first connection will be closed and ``connectionDidClose()`` will return for
     /// the previous connection.
-    ///
     static func connection() async throws -> Connection
 
     /// Close the current Connection.
     ///
     /// This closes the connection sending the optional error to the ``connectionDidClose()`` method.
     func close(error: Error?) async
 
+    /// Wait for the connection to close.
+    /// 
     /// This method will wait until the connection closes. If the connection was closed due to an error said
     /// error will be returned.
     func connectionDidClose() async -> Error?
 
-    /// Send a APDU to the Connection. Commands that need multiple reads from the YubiKey will
-    /// be handled automatically and returning a Response only when all data has been read from the
-    /// YubiKey.
+    /// Send an APDU to the Connection.
+    ///
+    /// This will send the APDU to the YubiKey using the Connection. Commands returning data to big
+    /// to be handled by a single read operation will be handled automatically by the SDK and the
+    /// complete result will be returned by the function. Only operations returning a 0x9100 status
+    /// code will return data. Operations returning a 0x61XX (more data) status code will be handled
+    /// by the SDK until they finish with a 0x9100 or an error. For all other status codes a ResponseError
+    /// wrapping the status code will be thrown.
     func send(apdu: APDU) async throws -> Data
 }
 

YubiKit/YubiKit/LightningConnection.swift

@@ -18,6 +18,7 @@ import Foundation
 import ExternalAccessory
 
 /// A connection to the YubiKey utilizing the Lightning port and External Accessory framework.
+@available(iOS 16.0, *)
 public final actor LightningConnection: Connection, InternalConnection {
 
     private static let manager = LightningConnectionManager()

YubiKit/YubiKit/Management/ManagementSession.swift

@@ -21,6 +21,7 @@ enum ManagementSessionError: Error {
     case versionParseError
 }
 
+/// An interface to the Management application on the YubiKey.
 public final actor ManagementSession: Session, InternalSession {
 
     var _connection: Connection?

YubiKit/YubiKit/NFCConnection.swift

@@ -24,6 +24,7 @@ import CoreNFC
 /// method that will close the connection and set the alertMessage of the NFC alert to the provided message.
 ///
 /// > Note: NFC is only supported on iPhones from iPhone 6 and forward. It will not work on iPads since there's no NFC chip in these devices.
+@available(iOS 16.0, *)
 public final actor NFCConnection: Connection, InternalConnection {
 
     private static let manager = NFCConnectionManager()

YubiKit/YubiKit/OATH/OATHSession.swift

@@ -38,6 +38,11 @@ public enum OATHSessionError: Error {
     case credentialNotPresentOnCurrentYubiKey
 }
 
+/// An interface to the OATH application on the YubiKey.
+///
+/// The OATHSession is an interface to the OATH appcliation on the YubiKey that will
+/// let you store, calculate and edit TOTP and HOTP credentials on the YubiKey. Learn
+/// more about OATH on the [Yubico developer website](https://developers.yubico.com/OATH/).
 public final class OATHSession: Session, InternalSession {
     func connection() async -> Connection? {
         return _connection

YubiKit/YubiKit/Session.swift

@@ -14,7 +14,7 @@
 
 import Foundation
 
-/// An interface defining a session with a specific application on the YubiKey.
+/// A protocol defining a session with a specific application on the YubiKey.
 ///
 /// The Session uses a ``Connection`` to handle communication with the YubiKey. Using a session is the preferred way
 /// of communicating with the different applications on the YubiKey.

YubiKit/YubiKit/SmartCardConnection.swift

@@ -15,7 +15,9 @@
 import Foundation
 import CryptoTokenKit
 
-/// A connection to the YubiKey utilizing the USB-C port and TKSmartCard implementation.
+/// A connection to the YubiKey utilizing the USB-C port and the TKSmartCard implementation from
+/// the CryptoTokenKit framework.
+@available(iOS 16.0, macOS 13.0, *)
 public final actor SmartCardConnection: Connection, InternalConnection {
 
     private static let manager = SmartCardManager()

YubiKit/YubiKit/Utilities/ConnectionHelper.swift

@@ -17,6 +17,8 @@ import Foundation
 import CoreNFC
 #endif
 
+/// ConnectionHelper simplifies the creation of different connections to the YubiKey by automate
+/// much of the work involved in handling multiple different connection at the same time.
 public enum ConnectionHelper {
 
     public static func anyConnection(nfcAlertMessage: String? = nil) async throws -> Connection {

YubiKit/YubiKit/YubiKit.docc/Resources/YubiKit.md

@@ -3,11 +3,12 @@
 Connect and run commands on the different applications on a YubiKey. The framework support connecting using NFC, Lightning and USB-C.
 
 @Metadata {
-    @PageImage(
-        purpose: icon, 
-        source: "documentation-header", 
-        alt: "A technology icon representing the SlothCreator framework.")
+    @PageImage(purpose: icon, 
+               source: "documentation-header", 
+               alt: "A technology icon representing the SlothCreator framework.")
     @PageColor(green)
+    @Available(macOS, introduced: "13.0")
+    @Available(iOS, introduced: "16.0")
 }
 
 ## Overview
@@ -34,8 +35,9 @@ transitioning from the old Objective-C SDK.
 ### Creating a Connection to a YubiKey
 
 The implementations of the Connection protocol handles the connection to the YubiKey and can be used to send
-data in the form of a ``APDU`` to the YubiKey. However, in most cases the Connection is used to create
-a Session to a application in the YubiKey. This Session is then used to execute commands on the YubiKey.
+data in the form of a ``APDU`` to the YubiKey. In most cases it is adviced to use one of the supplied Sessions
+(``OATHSession``, ``ManagementSession``) instead of sending raw APDUs to the YubiKey.
+
 
 - ``Connection``
 - ``NFCConnection``
@@ -45,8 +47,10 @@ a Session to a application in the YubiKey. This Session is then used to execute
 
 ### Sending and receiving data
 
+Use the default implementation of ``Connection/send(apdu:)-7bmw4`` to send data to the YubiKey using the Connection.
+This will either return the full response data or throw a ``ResponseError``.
+
 - ``APDU``
-- ``Response``
 
 ### Creating a Session
 
@@ -57,6 +61,8 @@ communication with the YubiKey.
 - ``Session``
 - ``OATHSession``
 - ``ManagementSession``
+- ``DeviceInfo``
+- ``DeviceConfig``
 
 ### Using the wrappers