chore(core): Enhanced swift documentation

Author: jcjimenez

Amplify/Amplify.swift

@@ -18,27 +18,51 @@ import Foundation
 ///
 /// There are two exceptions to this. The `Logging` and `Hub` categories are configured with a default plugin that is
 /// available at initialization.
+///
+/// - Tag: Amplify
 public class Amplify {
 
     /// If `true`, `configure()` has already been invoked, and subsequent calls to `configure` will throw a
     /// ConfigurationError.amplifyAlreadyConfigured error.
+    ///
+    /// - Tag: Amplify.isConfigured
     static var isConfigured = false
 
     // Storage for the categories themselves, which will be instantiated during configuration, and cleared during reset.
     // It is not supported to mutate these category properties. They are `var` to support the `reset()` method for
     // ease of testing.
+
+    /// - Tag: Amplify.Analytics
     public static internal(set) var Analytics = AnalyticsCategory()
+
+    /// - Tag: Amplify.API
     public static internal(set) var API: APICategory = APICategory()
+
+    /// - Tag: Amplify.Auth
     public static internal(set) var Auth = AuthCategory()
+
+    /// - Tag: Amplify.DataStore
     public static internal(set) var DataStore = DataStoreCategory()
+
+    /// - Tag: Amplify.Geo
     public static internal(set) var Geo = GeoCategory()
+
+    /// - Tag: Amplify.Hub
     public static internal(set) var Hub = HubCategory()
+
+    /// - Tag: Amplify.Notifications
     public static internal(set) var Notifications = NotificationsCategory()
+
+    /// - Tag: Amplify.Predictions
     public static internal(set) var Predictions = PredictionsCategory()
+
+    /// - Tag: Amplify.Storage
     public static internal(set) var Storage = StorageCategory()
 
-    // Special case category. We protect this with an AtomicValue because it is used by reset()
-    // methods during setup & teardown of tests
+    /// Special case category. We protect this with an AtomicValue because it is used by reset()
+    /// methods during setup & teardown of tests
+    ///
+    /// - Tag: Amplify.Logging
     public static internal(set) var Logging: LoggingCategory {
         get {
             loggingAtomic.get()
@@ -51,7 +75,10 @@ public class Amplify {
 
     /// Adds `plugin` to the category
     ///
+    /// See: [Category.removePlugin(for:)](x-source-tag://Category.removePlugin)
+    ///
     /// - Parameter plugin: The plugin to add
+    /// - Tag: Amplify.add_plugin
     public static func add<P: Plugin>(plugin: P) throws {
         log.debug("Adding plugin: \(plugin))")
         switch plugin {

Amplify/Core/Category/Category+Logging.swift

@@ -7,6 +7,8 @@
 
 public extension Category {
     /// A default logger for the category
+    ///
+    /// - Tag: Category.log
     var log: Logger {
         Amplify.Logging.logger(forCategory: categoryType.displayName)
     }

Amplify/Core/Category/Category.swift

@@ -7,6 +7,8 @@
 
 /// An Amplify Category stores certain global states, holds references to plugins for the category, and routes method
 /// requests to those plugins appropriately.
+///
+/// - Tag: Category
 public protocol Category: AnyObject, CategoryTypeable, DefaultLogger {
 
     // NOTE: `add(plugin:)` and `getPlugin(for key:)` must be implemented in the actual category classes, since they
@@ -15,7 +17,10 @@ public protocol Category: AnyObject, CategoryTypeable, DefaultLogger {
     /// Removes the plugin registered for `key` from the list of Plugins that implement functionality for this category.
     /// If no plugin has been added for `key`, no action is taken, making this method safe to call multiple times.
     ///
+    /// See: [Amplify.add(plugin:)](x-source-tag://Amplify.add_plugin)
+    ///
     /// - Parameter key: The key used to `add` the plugin
+    /// - Tag: Category.removePlugin
     func removePlugin(for key: PluginKey)
 
 }

Amplify/Core/Category/CategoryType.swift

@@ -7,46 +7,72 @@
 
 /// The Amplify category with which the conforming type is associated. Categories, Plugins, ClientBehaviors, etc must
 /// all share the same CategoryType
+///
+/// - Tag: CategoryTypeable
 public protocol CategoryTypeable {
+    /// - Tag: CategoryTypeable.categoryType
     var categoryType: CategoryType { get }
 }
 
 /// Amplify supports these Category types
+///
+/// - Tag: CategoryType
 public enum CategoryType: String {
     /// Record app metrics and analytics data
+    ///
+    /// - Tag: CategoryType.analytics
     case analytics
 
     /// Retrieve data from a remote service
+    ///
+    /// - Tag: CategoryType.api
     case api
 
     /// Authentication
+    ///
+    /// - Tag: CategoryType.auth
     case auth
 
     /// Persist data
+    ///
+    /// - Tag: CategoryType.dataStore
     case dataStore
 
     /// Interact with geospatial services
+    ///
+    /// - Tag: CategoryType.geo
     case geo
 
     /// Listen for or dispatch Amplify events
+    ///
+    /// - Tag: CategoryType.hub
     case hub
 
     /// Log Amplify and app messages
+    ///
+    /// - Tag: CategoryType.logging
     case logging
 
     /// Prediction
+    ///
+    /// - Tag: CategoryType.predictions
     case predictions
 
     /// Push Notifications
+    ///
+    /// - Tag: CategoryType.pushNotifications
     case pushNotifications
 
     /// Upload and download files from the cloud
+    ///
+    /// - Tag: CategoryType.storage
     case storage
 }
 
 extension CategoryType: CaseIterable {}
 
 public extension CategoryType {
+    /// - Tag: CategoryType.displayName
     var displayName: String {
         switch self {
         case .analytics:
@@ -72,6 +98,7 @@ public extension CategoryType {
         }
     }
 
+    /// - Tag: CategoryType.category
     var category: Category {
         switch self {
         case .analytics:

Amplify/Core/Configuration/AmplifyConfiguration.swift

@@ -7,7 +7,11 @@
 
 import Foundation
 
-/// Configures the Amplify system with sub-configurations for each supported category
+/// Represents Amplify's configuration for all categories intended to be used in an application.
+///
+/// See: [Amplify.configure](x-source-tag://Amplify.configure)
+///
+/// - Tag: AmplifyConfiguration
 public struct AmplifyConfiguration: Codable {
     enum CodingKeys: String, CodingKey {
         case analytics
@@ -52,6 +56,7 @@ public struct AmplifyConfiguration: Codable {
     /// Configurations for the Amplify Storage category
     let storage: StorageCategoryConfiguration?
 
+    /// - Tag: Amplify.init
     public init(analytics: AnalyticsCategoryConfiguration? = nil,
                 api: APICategoryConfiguration? = nil,
                 auth: AuthCategoryConfiguration? = nil,
@@ -75,6 +80,8 @@ public struct AmplifyConfiguration: Codable {
     }
 
     /// Initialize `AmplifyConfiguration` by loading it from a URL representing the configuration file.
+    ///
+    /// - Tag: Amplify.configureWithConfigurationFile
     public init(configurationFile url: URL) throws {
         self = try AmplifyConfiguration.loadAmplifyConfiguration(from: url)
     }
@@ -100,6 +107,8 @@ extension Amplify {
     /// event to each Amplify Hub channel. After this point, plugins may invoke calls on other Amplify categories.
     ///
     /// - Parameter configuration: The AmplifyConfiguration for specified Categories
+    ///
+    /// - Tag: Amplify.configure
     public static func configure(_ configuration: AmplifyConfiguration? = nil) throws {
         log.info("Configuring")
         log.debug("Configuration: \(String(describing: configuration))")

Amplify/Core/Configuration/CategoryConfiguration.swift

@@ -6,8 +6,12 @@
 //
 
 /// A CategoryConfiguration must contain a plugins field used to configure plugins for that category
+///
+/// - Tag: CategoryConfiguration
 public protocol CategoryConfiguration: Codable {
     /// A map of category plugin configurations by PluginKey. Such configurations are defined by the plugins
     /// themselves, and may be of any type.
+    ///
+    /// - Tag: CategoryConfiguration.plugins
     var plugins: [String: JSONValue] { get }
 }

Amplify/Core/Configuration/ConfigurationError.swift

@@ -6,21 +6,34 @@
 //
 
 /// Errors associated with configuring and inspecting Amplify Categories
+///
+/// See: [Amplify.configure](x-source-tag://Amplify.configure)
+/// 
+/// - Tag: ConfigurationError
 public enum ConfigurationError {
     /// The client issued a subsequent call to `Amplify.configure` after the first had already succeeded
+    ///
+    /// - Tag: ConfigurationError.amplifyAlreadyConfigured
     case amplifyAlreadyConfigured(ErrorDescription, RecoverySuggestion, Error? = nil)
 
     /// The specified `amplifyconfiguration.json` file was not present or unreadable
+    ///
+    /// - Tag: ConfigurationError.invalidAmplifyConfigurationFile
     case invalidAmplifyConfigurationFile(ErrorDescription, RecoverySuggestion, Error? = nil)
 
     /// Unable to decode `amplifyconfiguration.json` into a valid AmplifyConfiguration object
+    ///
+    /// - Tag: ConfigurationError.unableToDecode
     case unableToDecode(ErrorDescription, RecoverySuggestion, Error? = nil)
 
     /// An unknown error occurred
+    ///
+    /// - Tag: ConfigurationError.unknown
     case unknown(ErrorDescription, RecoverySuggestion, Error?)
 }
 
 extension ConfigurationError: AmplifyError {
+    /// - Tag: ConfigurationError.errorDescription
     public var errorDescription: ErrorDescription {
         switch self {
         case .amplifyAlreadyConfigured(let description, _, _),
@@ -31,6 +44,7 @@ extension ConfigurationError: AmplifyError {
         }
     }
 
+    /// - Tag: ConfigurationError.recoverySuggestion
     public var recoverySuggestion: RecoverySuggestion {
         switch self {
         case .amplifyAlreadyConfigured(_, let recoverySuggestion, _),
@@ -41,6 +55,7 @@ extension ConfigurationError: AmplifyError {
         }
     }
 
+    /// - Tag: ConfigurationError.underlyingError
     public var underlyingError: Error? {
         switch self {
         case .amplifyAlreadyConfigured(_, _, let underlyingError),
@@ -51,6 +66,7 @@ extension ConfigurationError: AmplifyError {
         }
     }
 
+    /// - Tag: ConfigurationError.init
     public init(
         errorDescription: ErrorDescription = "An unknown error occurred",
         recoverySuggestion: RecoverySuggestion = "See `underlyingError` for more details",

Amplify/Core/Error/CoreError.swift

@@ -6,16 +6,23 @@
 //
 
 /// Errors associated with operations provided by Amplify
+///
+/// - Tag: CoreError
 public enum CoreError {
 
     /// A related operation performed on `List` resulted in an error.
+    ///
+    /// - Tag: CoreError.listOperation
     case listOperation(ErrorDescription, RecoverySuggestion, Error? = nil)
 
     /// A client side validation error occured.
+    ///
+    /// - Tag: CoreError.clientValidation
     case clientValidation(ErrorDescription, RecoverySuggestion, Error? = nil)
 }
 
 extension CoreError: AmplifyError {
+    /// - Tag: CoreError.errorDescription
     public var errorDescription: ErrorDescription {
         switch self {
         case .listOperation(let errorDescription, _, _),
@@ -24,6 +31,7 @@ extension CoreError: AmplifyError {
         }
     }
 
+    /// - Tag: CoreError.recoverySuggestion
     public var recoverySuggestion: RecoverySuggestion {
         switch self {
         case .listOperation(_, let recoverySuggestion, _),
@@ -32,6 +40,7 @@ extension CoreError: AmplifyError {
         }
     }
 
+    /// - Tag: CoreError.underlyingError
     public var underlyingError: Error? {
         switch self {
         case .listOperation(_, _, let underlyingError),
@@ -40,6 +49,7 @@ extension CoreError: AmplifyError {
         }
     }
 
+    /// - Tag: CoreError.init
     public init(
         errorDescription: ErrorDescription = "An unknown error occurred",
         recoverySuggestion: RecoverySuggestion = "(Ignored)",