Swift-ify Documentation

Changes to documentation to align more with DocC

README.md

@@ -247,7 +247,7 @@ class MyCustomClass: TurboNavigationDelegate {
     func handle(proposal: VisitProposal) -> ProposalResult {
         if proposal.viewController == "numbers" {
             // Let Turbo Navigator route this custom controller.
-            return NumbersViewController()
+            return .acceptCustom(NumbersViewController())
         } else if proposal.presentation == .clearAll {
             // Return nil to tell Turbo Navigator stop processing the request.
             return nil

Sources/PathConfigurationIdentifiable.swift

@@ -1,13 +1,14 @@
 import UIKit
 
 /// As a convenience, your view controller may conform to `PathConfigurationIdentifiable`.
+/// 
 /// You may then use the view controller's `pathConfigurationIdentifier` property instead of `proposal.url` when deciding how to handle a proposal. See `VisitProposal.viewController` on how to use this in your configuration file.
 ///
-/// ```
+/// ```swift
 /// func handle(proposal: VisitProposal) -> ProposalResult {
 ///    switch proposal.viewController {
 ///    case RecipeViewController.pathConfigurationIdentifier:
-///        return .accept(RecipeViewController.new)
+///        return .acceptCustom(RecipeViewController())
 ///    default:
 ///        return .accept
 ///    }

Sources/ProposalResult.swift

@@ -1,6 +1,6 @@
 import UIKit
 
-/// Return from `handle(proposal:)` to route a custom controller.
+/// Return from `TurboNavigationDelegate.handle(proposal:)` to route a custom controller.
 public enum ProposalResult: Equatable {
     /// Route a `VisitableViewController`.
     case accept

Sources/TurboConfig.swift

@@ -6,7 +6,7 @@ public class TurboConfig {
     public static let shared = TurboConfig()
 
     /// Override to set a custom user agent.
-    /// Include "Turbo Native" to use `turbo_native_app?` on your Rails server.
+    /// - Important: Include "Turbo Native" to use `turbo_native_app?` on your Rails server.
     public var userAgent = "Turbo Native iOS"
 
     /// Optionally customize the web views used by each Turbo Session.

Sources/TurboNavigationDelegate.swift

@@ -10,29 +10,36 @@ public protocol TurboNavigationDelegate: AnyObject {
     /// Respond to authentication challenge presented by web servers behing basic auth.
     func didReceiveAuthenticationChallenge(_ challenge: URLAuthenticationChallenge, completionHandler: @escaping (URLSession.AuthChallengeDisposition, URLCredential?) -> Void)
 
-    /// Optional. Accept or reject a visit proposal.
-    /// If accepted, you may provide a view controller to be displayed, otherwise a new `VisitableViewController` is displayed.
-    /// If rejected, no changes to navigation occur.
-    /// If not implemented, proposals are accepted and a new `VisitableViewController` is displayed.
+    /// Accept or reject a visit proposal.
     ///
-    /// - Parameter proposal: navigation destination
-    /// - Returns: how to react to the visit proposal
+    /// There are three `ProposalResult` cases:
+    ///    - term `accept`: Proposals are accepted and a new `VisitableViewController` is displayed.
+    ///    - term `acceptCustom(UIViewController)`: You may provide a view controller to be displayed, otherwise a new `VisitableViewController` is displayed.
+    ///    - term `reject`: No changes to navigation occur.
+    ///
+    /// - Parameter proposal: `VisitProposal` navigation destination
+    /// - Returns:`ProposalResult` - how to react to the visit proposal
+    /// - Note: optional
     func handle(proposal: VisitProposal) -> ProposalResult
 
-    /// Optional. An error occurred loading the request, present it to the user.
+    /// An error occurred loading the request, present it to the user.
     /// Retry the request by executing the closure.
     /// If not implemented, will present the error's localized description and a Retry button.
+    /// - Note: optional
     func visitableDidFailRequest(_ visitable: Visitable, error: Error, retry: @escaping RetryBlock)
 
-    /// Optional. Implement to customize handling of external URLs.
+    /// Implement to customize handling of external URLs.
     /// If not implemented, will present `SFSafariViewController` as a modal and load the URL.
+    /// - Note: optional
     func openExternalURL(_ url: URL, from controller: UIViewController)
 
-    /// Optional. Implement to become the web view's navigation delegate after the initial cold boot visit is completed.
+    /// Implement to become the web view's navigation delegate after the initial cold boot visit is completed.
     /// https://github.com/hotwired/turbo-ios/blob/main/Docs/Overview.md#becoming-the-web-views-navigation-delegate
+    /// - Note: optional
     func sessionDidLoadWebView(_ session: Session)
 
-    /// Optional. Useful for interacting with the web view after the page loads.
+    /// Useful for interacting with the web view after the page loads.
+    /// - Note: optional
     func sessionDidFinishRequest(_ session: Session)
 }
 

Sources/TurboNavigator.swift

@@ -4,14 +4,14 @@ import UIKit
 import WebKit
 
 /// Handles navigation to new URLs using the following rules:
-/// https://github.com/joemasilotti/TurboNavigator#handled-flows
+/// [Turbo Navigator Handled Flows](https://github.com/joemasilotti/TurboNavigator#handled-flows)
 public class TurboNavigator {
     /// Default initializer.
     /// - Parameters:
     ///   - delegate: handle custom controller routing
     ///   - pathConfiguration: assigned to internal `Session` instances for custom configuration
-    ///   - navigationController: optional: override the main navigation stack
-    ///   - modalNavigationController: optional: override the modal navigation stack
+    ///   - navigationController: _optional:_ override the main navigation stack
+    ///   - modalNavigationController: _optional:_ override the modal navigation stack
     public init(delegate: TurboNavigationDelegate,
                 pathConfiguration: PathConfiguration? = nil,
                 navigationController: UINavigationController = UINavigationController(),
@@ -30,13 +30,15 @@ public class TurboNavigator {
     }
 
     /// Provide `Turbo.Session` instances with preconfigured path configurations and delegates.
-    /// Note that TurboNavigationDelegate.controller(_:forProposal:) will no longer be called.
+    ///
     /// - Parameters:
     ///   - preconfiguredMainSession: a session whose delegate is not `TurboNavigator`
     ///   - preconfiguredModalSession: a session whose delegate is not `TurboNavigator`
     ///   - delegate: handle non-routing behavior, like custom error handling
-    ///   - navigationController: optional: override the main navigation stack
-    ///   - modalNavigationController: optional: override the modal navigation stack
+    ///   - navigationController: _optional:_ override the main navigation stack
+    ///   - modalNavigationController: _optional:_ override the modal navigation stack
+    ///
+    /// - Note: `TurboNavigationDelegate.handle(proposal:)` will no longer be called.
     public init(preconfiguredMainSession: Turbo.Session,
                 preconfiguredModalSession: Turbo.Session,
                 delegate: TurboNavigationDelegate,

Sources/VisitProposalExtension.swift

@@ -20,7 +20,7 @@ public extension VisitProposal {
     ///
     /// For example, given the following configuration file:
     ///
-    /// ```
+    /// ```json
     /// {
     ///   "rules": [
     ///     {
@@ -35,9 +35,12 @@ public extension VisitProposal {
     /// }
     /// ```
     ///
-    /// A VisitProposal to `https://example.com/recipes/` will have `proposal.viewController == "recipes"`
+    /// A VisitProposal to `https://example.com/recipes/` will have
+    /// ```swift
+    /// proposal.viewController == "recipes" 
+    /// ```
     ///
-    /// A default value is provided in case the view controller property is missing from the configuration file. This will route the default `VisitableViewController`.
+    /// - Important: A default value is provided in case the view controller property is missing from the configuration file. This will route the default `VisitableViewController`.
     var viewController: String {
         if let viewController = properties["view-controller"] as? String {
             return viewController