Update readme and internal documentation (#39)

This tidies up some of the README information, including the addition of
links to the new SPI source-generated documentation.

Additionally, it clarifies some examples around username and removes
some outdated documentation comments around delegate methods.

README.md

@@ -3,15 +3,22 @@
 This is the official Swift SDK for [SnapAuth](https://www.snapauth.app?utm_source=GitHub&utm_campaign=sdk&utm_content=sdk-swift).
 
 SnapAuth will let you add passkey support to your native app in a snap!
+Add strong multi-factor authentication or go fully passwordless while maintaining a great, frictionless user experience.
 
-🚧 This SDK is in beta! 🚧
+[SnapAuth Homepage](https://www.snapauth.app?utm_source=GitHub&utm_campaign=sdk&utm_content=sdk-swift)
+| [SnapAuth Docs](https://docs.snapauth.app)
+| [Dashboard](https://dashboard.snapauth.app)
+| [Github](https://github.com/snapauthapp/sdk-swift)
 
-![GitHub License](https://img.shields.io/github/license/snapauthapp/sdk-typescript)
+[![GitHub Release](https://img.shields.io/github/v/release/snapauthapp/sdk-swift)](https://github.com/snapauthapp/sdk-swift/releases)
+[![Test](https://github.com/snapauthapp/sdk-swift/actions/workflows/test.yml/badge.svg)](https://github.com/snapauthapp/sdk-swift/actions/workflows/test.yml)
+[![GitHub License](https://img.shields.io/github/license/snapauthapp/sdk-typescript)](https://github.com/snapauthapp/sdk-swift/blob/main/LICENSE)
 
-- [SnapAuth Homepage](https://www.snapauth.app?utm_source=GitHub&utm_campaign=sdk&utm_content=sdk-swift)
-- [Docs](https://docs.snapauth.app)
-- [Dashboard](https://dashboard.snapauth.app)
-- [Github](https://github.com/snapauthapp/sdk-swift)
+![Swift Versions](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fsnapauthapp%2Fsdk-swift%2Fbadge%3Ftype%3Dswift-versions)
+![Supported Platforms](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fsnapauthapp%2Fsdk-swift%2Fbadge%3Ftype%3Dplatforms)
+
+[Swift Package Index](https://swiftpackageindex.com/snapauthapp/sdk-swift)
+| [SPI docs](https://swiftpackageindex.com/snapauthapp/sdk-swift/main/documentation/snapauth)
 
 ## Platform Support
 
@@ -25,7 +32,9 @@ macOS | ✅ 12.0+ | ✅ 12.0+ |
 macOS (Catalyst) | ⚠️ | ⚠️ | Still being tested (should work)
 visionOS | ✅ 1.0+ | ❌ | Hardware keys are not supported on visionOS
 tvOS | ⚠️ 16.0+ | ❌ | Still being tested, hardware keys are not supported on tvOS
-watchOS | ❌ | ❌ | Apple Watch does not support passkeys
+
+Apple Watch does not support passkeys or hardware keys, so watchOS is not supported by this SDK.
+If support is added in a future watchOS release, we will do the same!
 
 ## Getting Started
 

Sources/SnapAuth/SnapAuth+ASACD.swift

@@ -4,6 +4,8 @@ import AuthenticationServices
 @available(macOS 12.0, iOS 15.0, visionOS 1.0, tvOS 16.0, *)
 extension SnapAuth: ASAuthorizationControllerDelegate {
 
+    /// Delegate method for ASAuthorizationController.
+    /// This should not be called directly.
     public func authorizationController(
         controller: ASAuthorizationController,
         didCompleteWithError error: Error
@@ -20,6 +22,8 @@ extension SnapAuth: ASAuthorizationControllerDelegate {
         // ASAuthorizationController credential request failed with error: Error Domain=com.apple.AuthenticationServices.AuthorizationError Code=1004 "(null)"
     }
 
+    /// Delegate method for ASAuthorizationController.
+    /// This should not be called directly.
     public func authorizationController(
         controller: ASAuthorizationController,
         didCompleteWithAuthorization authorization: ASAuthorization
@@ -38,7 +42,6 @@ extension SnapAuth: ASAuthorizationControllerDelegate {
         }
     }
 
-    /// Sends the error to the appropriate delegate method and resets the internal state back to idle
     private func sendError(_ error: SnapAuthError) {
         continuation?.resume(returning: .failure(error))
         continuation = nil
@@ -47,7 +50,6 @@ extension SnapAuth: ASAuthorizationControllerDelegate {
     private func handleRegistration(
         _ registration: ASAuthorizationPublicKeyCredentialRegistration
     ) {
-        // Decode, send to SA, hand back resposne via delegate method
         logger.info("got a registration response")
 
         let credentialId = Base64URL(from: registration.credentialID)

Sources/SnapAuth/SnapAuth+ASACPCP.swift

@@ -3,6 +3,8 @@ import AuthenticationServices
 // MARK: ASAuthorizationControllerPresentationContextProviding
 @available(macOS 12.0, iOS 15.0, tvOS 16.0, visionOS 1.0, *)
 extension SnapAuth: ASAuthorizationControllerPresentationContextProviding {
+    /// Delegate method for ASAuthorizationController.
+    /// This should not be called directly.
     public func presentationAnchor(for controller: ASAuthorizationController) -> ASPresentationAnchor {
         guard anchor != nil else {
             // There's currently no logical path here since the three

Sources/SnapAuth/SnapAuth.swift

@@ -71,21 +71,24 @@ public class SnapAuth: NSObject { // NSObject for ASAuthorizationControllerDeleg
         }
     }
 
-    /// Starts the passkey enrollment process.
-    /// Upon completion, the delegate will be called with either success or failure.
+    /// Starts the passkey enrollment process by displaying a system dialog.
+    ///
+    /// The task will complete when the user approves or rejects the request, or
+    /// if the request cannot be fulfilled.
+    ///
     /// - Parameters:
-    ///   - name: The name of the user.
+    ///   - name: The name of the user. This should be a username or handle.
     ///   - displayName: The proper name of the user. If omitted, name will be used.
     ///   - authenticators: What authenticators should be permitted. If omitted,
-    ///   all available types for the platform will be allowed.
+    ///     all available types for the platform will be allowed.
     ///
     /// - Returns: A `Result` containing either `SnapAuthTokenInfo` upon success
     ///   or a `SnapAuthError` upon failure.
     ///
     /// # Example
     /// ```swift
     /// Task {
-    ///     let result = await snapAuth.startRegister(name: name)
+    ///     let result = await snapAuth.startRegister(name: "username@example.com")
     ///     switch result {
     ///     case .success(let registration):
     ///         // send registration.token to your backend to create the credential
@@ -149,12 +152,15 @@ public class SnapAuth: NSObject { // NSObject for ASAuthorizationControllerDeleg
 
     internal var authenticatingUser: AuthenticatingUser?
 
-    /// Starts the authentication process.
-    /// Upon completion, the delegate will be called with either success or failure.
+    /// Starts the authentication process by displaying a system dialog.
+    ///
+    /// The task will complete when the user approves or rejects the request, or
+    /// if the request cannot be fulfilled.
     ///
     /// - Parameters:
     ///   - user: The authenticating user's `id` or `handle`
-    ///   - authenticators: What authenticators should be permitted. If omitted, all available types for the platform will be allowed.
+    ///   - authenticators: What authenticators should be permitted. If omitted,
+    ///     all available types for the platform will be allowed.
     ///
     ///
     /// - Returns: A `Result` containing either `SnapAuthTokenInfo` upon success
@@ -163,7 +169,7 @@ public class SnapAuth: NSObject { // NSObject for ASAuthorizationControllerDeleg
     /// # Example
     /// ```swift
     /// Task {
-    ///     let result = await snapAuth.startAuth(.handle(userName))
+    ///     let result = await snapAuth.startAuth(.handle("username@example.com"))
     ///     switch result {
     ///     case .success(let auth):
     ///         // send auth.token to your backend to verify