docs: improve documentation

Author: mlbonniec

Sources/QuickActionsKit/QuickActions.swift

@@ -7,32 +7,69 @@
 
 import UIKit
 
-/// The protocol defining the quick actions list and actions for your application.
-/// 
-/// ```swift
-/// enum MyQuickActionsType: String, QuickActionsType {
-///     // …
-/// }
+/// A protocol that defines a collection of Quick Actions to expose to the system.
 ///
-/// final class MyQuickActions: QuickActions<MyQuickActionsType> {
-///     // …
-/// }
-/// ```
+/// Conform to `QuickActions` to provide a set of app-specific quick actions
+/// (e.g., Home screen quick actions on iOS) that can be transformed into
+/// `UIApplicationShortcutItem` instances and presented to the user.
+///
+/// The protocol is generic over an `ActionType` that must conform to
+/// `QuickActionType`, allowing you to define a strongly-typed domain of actions
+/// for your feature or application.
+///
+/// Usage:
+/// - Implement `actions()` to return a unique set of `QuickActionsItem<ActionType>`.
+/// - The items will be mapped to `UIApplicationShortcutItem` and truncated to `limit`.
+///
+/// - Note: The order of the returned items may affect which actions are shown
+///   when exceeding the limit; ensure `actions()` returns items in your desired priority.
+///
+/// - SeeAlso: `QuickActionType`, `QuickActionsItem`, `UIApplicationShortcutItem`
 public protocol QuickActions<ActionType> {
+    /// The associated action type describing the domain of quick actions.
+    ///
+    /// This type must conform to `QuickActionType` and typically represents
+    /// the cases or identifiers for the actions your app supports.
     associatedtype ActionType: QuickActionType
-
-    /// The limit of actions to display.
+    
+    /// The maximum number of quick actions to expose.
+    ///
+    /// This value is used to limit the number of actions that are
+    /// ultimately surfaced to the system. Implement to customize based on your
+    /// product needs or platform constraints.
+    ///
+    /// - Default: `Int.max`
     var limit: Int { get }
-
-    /// The list of dynamic actions.
+    
+    /// Provides the full set of available quick actions for this context.
+    ///
+    /// - Returns: A `Set` of `QuickActionsItem<ActionType>` representing unique actions.
+    /// - Important: Use a `Set` to avoid duplicate actions and to emphasize uniqueness.
+    /// - Note: The resulting set may be truncated to `limit` before being surfaced.
     func actions() -> Set<QuickActionsItem<ActionType>>
 }
 
+/// The default implementations for `QuickActions`.
 public extension QuickActions {
-    var limit: Int { 4 }
+    /// The default maximum number of quick actions.
+    ///
+    /// - Note: Implement in your conforming type to change the limit.
+    var limit: Int { Int.max }
 }
 
+/// Internal conveniences for transforming actions into system shortcut items.
 extension QuickActions {
+    
+    /// A mapped array of `UIApplicationShortcutItem` created from `actions()`,
+    /// limited to `limit` items.
+    ///
+    /// - Discussion: This property maps each `QuickActionsItem` to a
+    ///   `UIApplicationShortcutItem` using `QuickActionsMapper.map`, filters out
+    ///   any that cannot be mapped, preserves the original ordering provided by
+    ///   `actions()`, and then truncates to the configured `limit`.
+    ///
+    /// - Important: This property is intended for internal use when integrating
+    ///   with system APIs. Prefer implementing `actions()` when defining behavior.
     var shortcutItems: [UIApplicationShortcutItem] {
         Array(
             actions()

Sources/QuickActionsKit/QuickActionsHandler.swift

@@ -7,10 +7,66 @@
 
 import Foundation
 
+/// A protocol that defines a handler for executing quick actions within your app.
+/// 
+/// Conform to `QuickActionsHandler` to process and respond to a specific set of quick actions,
+/// typically originating from system integrations such as Home screen quick actions, widgets,
+/// notifications, or app-specific shortcuts. Implementers specify the concrete action type via
+/// the `ActionType` associated type and provide logic to handle those actions asynchronously.
+///
+/// This protocol is annotated with `@MainActor`, which means conforming types and their methods
+/// are isolated to the main actor. This ensures UI updates and other main-thread–bound work
+/// can be performed safely while handling actions.
+///
+/// - Note: `ActionType` must conform to `QuickActionType`, which defines the model or descriptor
+///   for an action that can be invoked. Make sure your `ActionType` encapsulates all the
+///   information needed to execute the action.
+///
+/// - SeeAlso: `QuickActionType`
+///
+/// ### Example
+/// ```swift
+/// enum MyQuickActionsType: String, QuickActionType {
+///     case foo, bar
+/// }
+///
+/// extension SceneDelegate: QuickActionsHandler {
+///     func handle(_ action: MyQuickActionsType, userInfo: [String:NSSecureCoding]?) async -> Bool {
+///         switch action {
+///         case .foo:
+///             // …
+///         case .bar:
+///             // …
+///         }
+///
+///         return true
+///     }
+/// }
+/// ```
 @MainActor
 public protocol QuickActionsHandler {
+    /// The concrete quick action type that this handler can process.
+    ///
+    /// Conforming types set `ActionType` to a specific type that models the action
+    /// to handle. This type must conform to `QuickActionType`.
     associatedtype ActionType: QuickActionType
-
-    func handle(_ action: ActionType, userInfo: [String: NSSecureCoding]?) async -> Bool
+    
+    /// Handles a quick action asynchronously on the main actor.
+    ///
+    /// Implement this method to execute the logic associated with the given `action`.
+    /// Use `userInfo` to receive additional, optional metadata that may be required
+    /// to complete the action (for example, identifiers, prefilled content, or flags).
+    ///
+    /// - Parameters:
+    ///   - action: The quick action to be handled. Its type is defined by `ActionType`.
+    ///   - userInfo: An optional dictionary of additional information provided with the
+    ///               action. Values must conform to `NSSecureCoding` to ensure secure
+    ///               serialization and transport.
+    ///
+    /// - Returns: `true` if the action was recognized and successfully handled; `false`
+    ///            if the action could not be handled or was not applicable.
+    ///
+    /// - Note: Since this method is `async` and the protocol is `@MainActor`,
+    ///              you can safely perform UI operations directly within the handler.
+    func handle(_ action: ActionType, userInfo: [String:NSSecureCoding]?) async -> Bool
 }
-

Sources/QuickActionsKit/QuickActionsItem.swift

@@ -8,9 +8,72 @@
 import UIKit
 
 /// Represents the enum containing all the quick action types available for your application.
+/// A marker protocol that identifies a type-safe identifier for Home Screen quick actions.
+///
+/// Conform your enumeration to `QuickActionType` to declare the complete, strongly-typed
+/// set of quick actions your app supports. The protocol refines several standard Swift
+/// protocols to ensure identifiers are safe to use across threads, easy to store, and
+/// stable to serialize:
+/// - `RawRepresentable` with `RawValue == String`: Each case must map to a unique string
+///   value, which is used by the system (e.g., `UIApplicationShortcutItem.type`) and for
+///   persistence or deep linking.
+/// - `Hashable`: Enables use in sets, dictionaries, and as stable identifiers.
+/// - `Sendable`: Ensures values can safely cross concurrency boundaries.
+///
+/// Typical usage:
+/// ```swift
+/// enum AppQuickAction: String, QuickActionType {
+///     case note, search, favorites
+/// }
+/// ```
+///
+/// See also:
+/// - ``QuickActionsItem`` for modeling a full quick action entry presented to the user.
 public protocol QuickActionType: Sendable, RawRepresentable, Hashable where RawValue == String {}
 
 /// Represents a quick action item shown in the menu. 
+/// A value type that models a single Home Screen quick action entry for your app.
+///
+/// Use `QuickActionsItem` to describe the content and behavior of a quick action that
+/// appears in the system-provided menu (for example, via Home Screen icon context menu).
+/// Each item carries a strongly-typed identifier (`type`), user-visible strings (`title`
+/// and optional `subtitle`), an optional icon, and a Boolean that indicates whether the
+/// action is currently available.
+///
+/// - Generic Parameter:
+///   - T: A concrete type conforming to ``QuickActionType`` that uniquely identifies
+///         the action. This enables type-safe handling and pattern matching of actions.
+///
+/// The struct conforms to `Hashable`. Two `QuickActionsItem` values are considered equal
+/// if, and only if, their `type` values are equal. This makes `type` the logical unique
+/// identifier for items, which is useful when storing items in sets or using them as
+/// dictionary keys.
+///
+/// Typical usage includes:
+/// - Defining an enum that conforms to ``QuickActionType`` to enumerate all actions.
+/// - Creating one `QuickActionsItem` per action with localized titles, optional subtitles,
+///   and an appropriate icon.
+/// - Toggling `availability` to dynamically include or exclude an action from the menu.
+///
+/// Example:
+/// ```swift
+/// enum AppQuickAction: String, QuickActionType {
+///     case note, search, favorites
+/// }
+///
+/// let item = QuickActionsItem<AppQuickAction>(
+///     type: .note,
+///     title: "New Note",
+///     subtitle: "Create a blank note",
+///     icon: .systemName("square.and.pencil"),
+///     availability: true
+/// )
+/// ```
+///
+/// - Note: The `icon` supports multiple representations, including system icon names and
+///   `UIApplicationShortcutIcon.IconType`, to integrate with the system quick action UI.
+///   
+/// - SeeAlso: ``QuickActionType`` and ``QuickActionsItem/Icon``
 public struct QuickActionsItem<T>: Hashable where T: QuickActionType {
     // MARK: Properties
     /// The unique quick action type.
@@ -51,6 +114,25 @@ public struct QuickActionsItem<T>: Hashable where T: QuickActionType {
 
 extension QuickActionsItem {
     // MARK: Data
+    /// Represents the visual symbol displayed alongside a quick action in the system menu.
+    /// 
+    /// Use `Icon` to describe how the quick action should appear visually. The enum supports
+    /// multiple representations to align with system-provided icons and custom assets.
+    ///
+    /// Cases:
+    /// - `type(UIApplicationShortcutIcon.IconType)`: Uses a predefined system shortcut icon
+    ///   provided by UIKit. This is the most native option and ensures visual consistency
+    ///   with system quick actions.
+    /// - `systemName(String)`: Uses an SF Symbols system image by name (e.g., "square.and.pencil").
+    ///   Prefer this when you want a modern, scalable symbol that follows system design.
+    /// - `template(String)`: Uses the name of a templated image asset in your app bundle.
+    ///   The image should be a monochrome, template-rendered asset suitable for tinting.
+    ///
+    /// Notes:
+    /// - Not all SF Symbols are available on all platform versions. Ensure compatibility for
+    ///   targeted iOS, iPadOS, or other Apple platforms.
+    /// - Template images should be provided as single-color assets intended for tinting.
+    /// - The exact rendering of the icon may vary based on the system UI and context.
     public enum Icon: Hashable {
         case type(UIApplicationShortcutIcon.IconType)
         case systemName(String)

Sources/QuickActionsKit/QuickActionsKit.docc/Configuration/ConfigurationStep2.swift

@@ -5,13 +5,15 @@ enum MyQuickActionsType: String, QuickActionType {
     case create
 }
 
-class MyQuickActions: QuickActions {
-    var actions: Set<QuickActionsItem<MyQuickActionsType>> = [
-        QuickActionsItem<MyQuickActionsType>(
-            type: .home,
-            title: "Go Home",
-            subtitle: "Redirect to Home",
-            icon: nil
-        )
-    ]
+final class MyQuickActions: QuickActions {
+    func getActions() -> Set<QuickActionsItem<MyQuickActionsType>> {
+        [
+            QuickActionsItem<MyQuickActionsType>(
+                type: .home,
+                title: "Go Home",
+                subtitle: "Redirect to Home",
+                icon: nil
+            )
+        ]
+    }
 }

Sources/QuickActionsKit/QuickActionsKit.docc/Configuration/ConfigurationStep3.swift

@@ -5,20 +5,22 @@ enum MyQuickActionsType: String, QuickActionType {
     case create
 }
 
-class MyQuickActions: QuickActions {
-    var actions: Set<QuickActionsItem<MyQuickActionsType>> = [
-        QuickActionsItem<MyQuickActionsType>(
-            type: .home,
-            title: "Go Home",
-            subtitle: "Redirect to Home",
-            icon: nil
-        ),
-        QuickActionsItem<MyQuickActionsType>(
-            type: .create,
-            title: "Create",
-            subtitle: nil,
-            icon: .systemName("plus"),
-            availability: MyApplicationSingleton.current.isUserLogged
-        )
-    ]
+final class MyQuickActions: QuickActions {
+    func getActions() -> Set<QuickActionsItem<MyQuickActionsType>> {
+        [
+            QuickActionsItem<MyQuickActionsType>(
+                type: .home,
+                title: "Go Home",
+                subtitle: "Redirect to Home",
+                icon: nil
+            ),
+            QuickActionsItem<MyQuickActionsType>(
+                type: .create,
+                title: "Create",
+                subtitle: nil,
+                icon: .systemName("plus"),
+                availability: MyApplicationSingleton.current.isUserLogged
+            )
+        ]
+    }
 }

Sources/QuickActionsKit/QuickActionsKit.docc/Configuration/ConfigurationStep4.swift

@@ -32,14 +32,6 @@
 
                 @Code(name: "MyQuickActions.swift", file: ConfigurationStep3)
             }
-            
-            @Step {
-                Implement the `perform` method to handle action selection.
-                
-                This method is called when a user taps a quick action from the Home Screen. Use the action type to navigate to the appropriate screen or trigger the corresponding feature.
-                
-                @Code(name: "MyQuickActions.swift", file: ConfigurationStep4)
-            }
         }
     }
 }

Sources/QuickActionsKit/QuickActionsKit.docc/Configuration/Defining-Your-QuickActions.tutorial

@@ -0,0 +1,17 @@
+import QuickActionsKit
+
+@MainActor
+class SceneDelegate: UIResponder, UIWindowSceneDelegate {}
+
+extension SceneDelegate: QuickActionsHandler {
+    func handle(_ action: MyQuickActionsType, userInfo: [String:any NSSecureCoding]?) async -> Bool {
+        switch action {
+        case .home:
+            // …
+        case .create:
+            // …
+        }
+
+        return true
+    }
+}