Improve Authentication documentation

Sources/SwiftKit/Authentication/Authentication.swift

@@ -11,9 +11,9 @@ import Foundation
 /**
  This struct represents a unique authentication.
  
- This struct currently only has an `id` but is still used to
- be able to extend the authentication info without having to
- change any authentication protocols.
+ This struct currently only has an ``id``, but is still used
+ to improve the authentication info without having to change
+ any authentication protocols.
  */
 public struct Authentication {
     
@@ -27,9 +27,8 @@ public struct Authentication {
 public extension Authentication {
     
     /**
-     This a "standard" authentication. It can be used if you
-     don't have a bunch of different authentication types in
-     your app.
+     This standard authentication type can be used if you do
+     not have many different authentications in your app.
      */
     static var standard: Authentication {
         Authentication(id: "com.swiftkit.auth.any")

Sources/SwiftKit/Authentication/AuthenticationService.swift

@@ -9,8 +9,8 @@
 import Foundation
 
 /**
- This protocol can be implemented by authenticating services
- that can be used to authenticate the current user.
+ This protocol can be implemented by any classes that can be
+ used to authenticate the user.
  */
 public protocol AuthenticationService: AnyObject {
     
@@ -26,8 +26,7 @@ public protocol AuthenticationService: AnyObject {
     func authenticateUser(for auth: Authentication, reason: String, completion: @escaping AuthCompletion)
     
     /**
-     Check if the service instance can authenticate the user
-     for a certain authentication type.
+     Check if the service instance can authenticate the user.
      */
     func canAuthenticateUser(for auth: Authentication) -> Bool
 }

Sources/SwiftKit/Authentication/AuthenticationServiceError.swift

@@ -9,10 +9,23 @@
 import Foundation
 
 /**
- This enum represents possible authentication service errors.
+ This enum represents various authentication errors that can
+ occur while a user is being authenticated.
  */
 public enum AuthenticationServiceError: Error, Equatable {
     
+    /**
+     The authentication failed.
+     */
     case authenticationFailed
+    
+    /**
+     The authentication failed with a certain error message.
+     */
+    case authenticationFailedWithErrorMessage(String)
+    
+    /**
+     The requested authentication type is not supported.
+     */
     case unsupportedAuthentication
 }

Sources/SwiftKit/Authentication/BiometricAuthenticationService.swift

@@ -11,28 +11,18 @@ import LocalAuthentication
 
 /**
  This authentication service uses `LocalAuthentication` such
- as `FaceID` or `TOuchID` to authenticate the user.
+ as `FaceID` or `TouchID` to authenticate the user.
  */
-@available(iOS 11.0, OSX 10.12.2, *)
 public class BiometricAuthenticationService: AuthenticationService {
     
-    
-    // MARK: - Initialization
-    
     public init() {}
     
     
-    // MARK: - Properties
-    
     private let policy = LAPolicy.deviceOwnerAuthenticationWithBiometrics
     
     
-    // MARK: - Public functions
-    
     /**
-     Authenticate the user for a certain authentication type,
-     provided that the service can authenticate the user for
-     the provided authentication type.
+     Authenticate the user for a certain authentication type.
      
      `reason` can be used to display information to the user.
      */
@@ -44,8 +34,11 @@ public class BiometricAuthenticationService: AuthenticationService {
     }
     
     /**
-     Check if the service instance can authenticate the user
-     for a certain authentication type.
+     Check if the service instance can authenticate the user.
+     
+     For instance, a user can disable authentication for the
+     app, which means that the service can no longer fulfill
+     it's intended use.
      */
     public func canAuthenticateUser(for auth: Authentication) -> Bool {
         var error: NSError?

Sources/SwiftKit/Authentication/CachedAuthenticationService.swift

@@ -9,19 +9,19 @@
 import Foundation
 
 /**
- This protocol can be implemented by services that can cache
- an authentication result, to avoid having to perform a real
- authentication operation if a successful authentication has
- already been performed.
+ This protocol can be implemented by any classes that can be
+ used to authenticate the user and cache the result to avoid
+ having to perform a real authentication if a successful one
+ has already been performed.
  
  For instance, you can reduce the number of times users have
  to perform biometric authentication to access critical data.
  
  Note that you can't rely on a cached authentication service
- to clear its cached state. Call `resetUserAuthentications()`
- or `resetUserAuthentication(for:)` as soon as this state is
- considered to be invalid, e.g. when your app is send to the
- background and a new user can open the app at a later time.
+ to clear its state. Call the ``resetUserAuthentications()``
+ or ``resetUserAuthentication(for:)`` function as soon as an
+ authenticated session becomes invalid, e.g. when the app is
+ sent to the background or new users log in.
  */
 public protocol CachedAuthenticationService: AuthenticationService {
     

Sources/SwiftKit/Authentication/CachedAuthenticationServiceProxy.swift

@@ -9,8 +9,8 @@
 import Foundation
 
 /**
- This service wraps another authentication service and keeps
- authentication results in a cache.
+ This class wraps another ``AuthenticationService`` instance
+ and keeps authentication results in a cache.
  */
 public class CachedAuthenticationServiceProxy: CachedAuthenticationService {
     
@@ -45,8 +45,7 @@ public class CachedAuthenticationServiceProxy: CachedAuthenticationService {
     }
     
     /**
-     Check if the service instance can authenticate the user
-     for a certain authentication type.
+     Check if the service instance can authenticate the user.
      */
     public func canAuthenticateUser(for auth: Authentication) -> Bool {
         baseService.canAuthenticateUser(for: auth)