docs(All): 添加注释以及生成文档

Author: wxlpp

.jazzy.yaml

@@ -0,0 +1,7 @@
+module: UIRouter
+sdk: iphone
+swift_build_tool: xcodebuild
+podspec: UIRouter.podspec
+module_version: 1.0
+clean: true
+theme: theme/fullwidth

Example/shell/AppDelegate.swift

@@ -12,7 +12,7 @@ import UIRouter
 class AppDelegate: UIResponder, UIApplicationDelegate {
 
     func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
-        application.router.isNeedAutoRegister = true
+        application.router.autoRegisterIfNeed()
         application.router.register(interceptors: [WebInterceptor()])
         application.router.registerErrorHandler(RouteErrorHandler())
         return true

Source/Route.swift

@@ -7,7 +7,9 @@
 
 import UIKit
 
+/// 路由结果回调闭包
 public typealias RouteCompletionHandler<T> = (Result<T, Error>) -> Void
+/// 路由处理闭包
 public typealias RouterHandler<T> = (RouterParameters, @escaping RouteCompletionHandler<T>) -> Void
 
 struct Route<Output> {

Source/RouteError.swift

@@ -7,6 +7,8 @@
 
 import Foundation
 
+
+/// 路由错误
 public enum RouteError {
     /// 路由地址格式错误
     case badURL(url: String)
@@ -21,6 +23,8 @@ public enum RouteError {
 // MARK: - LocalizedError
 
 extension RouteError: LocalizedError {
+    
+    /// 错误信息
     public var errorDescription: String? {
         switch self {
         case .badURL(url: let url):
@@ -33,6 +37,8 @@ extension RouteError: LocalizedError {
             return "路由参数验证失败 路径[\(url)] 参数[\(name)]"
         }
     }
+    
+    /// 错误发生原因
     public var failureReason: String? {
         switch self {
         case .badURL(url: let url):

Source/RouteErrorHandling.swift

@@ -7,9 +7,20 @@
 
 import Foundation
 
+
+/// 实现`RouteErrorHandling`完成路由错误的集中处理
 public protocol RouteErrorHandling {
+    
+    /// 处理所有错误,已有默认实现,无需实现
+    /// - Parameter error: 任意错误
     func handle(error: Error)
+    
+    /// 处理路由错误
+    /// - Parameter error: 一个`RouteError`实例
     func handleRouteError(_ error: RouteError)
+    
+    /// 处理自定义错误
+    /// - Parameter error: 用户自定义的错误
     func handleCustomError(_ error: Error)
 }
 

Source/RouteResponse.swift Source/RouteRequest.swiftSource/RouteResponse.swift renamed to Source/RouteRequest.swift

@@ -1,13 +1,14 @@
 //
-//  RouteResponse.swift
+//  RouteRequest.swift
 //  UIRouter
 //
 //  Created by wxlpp on 2021/5/2.
 //
 
 import UIKit
 
-public final class RouteResponse {
+/// 路由请求包装,由此可以进行简便的页面跳转操作.
+public final class RouteRequest {
     var viewController: UIViewController?
 
     private let url: URLComponentsConvertible
@@ -16,22 +17,6 @@ public final class RouteResponse {
         self.url = url
     }
 
-    func asyncGetViewController(_ completionHandler: @escaping RouteCompletionHandler<UIViewController>) {
-        if let vc = viewController {
-            completionHandler(.success(vc))
-            return
-        }
-        UIViewControllerRouter.shared.route(url: url) { result in
-            switch result {
-            case .success(let vc):
-                self.viewController = vc
-            case .failure(let error):
-                UIViewControllerRouter.shared.errorHandler?.handle(error: error)
-            }
-            completionHandler(result)
-        }
-    }
-
     private func getVisibleViewController() -> UIViewController? {
         let keyWindow: UIWindow?
         if #available(iOS 13.0.0, *) {
@@ -47,9 +32,33 @@ public final class RouteResponse {
         return keyWindow?.rootViewController?.visibleViewController()
     }
 
+    
+    /// 异步获取路由结果页面
+    /// - Parameter completionHandler: 异步回调
+    public func asyncGetViewController(_ completionHandler: @escaping RouteCompletionHandler<UIViewController>) {
+        if let vc = viewController {
+            completionHandler(.success(vc))
+            return
+        }
+        UIViewControllerRouter.shared.route(url: url) { result in
+            switch result {
+                case .success(let vc):
+                    self.viewController = vc
+                case .failure(let error):
+                    UIViewControllerRouter.shared.errorHandler?.handle(error: error)
+            }
+            completionHandler(result)
+        }
+    }
+
+    /// 进行页面跳转
+    /// - Parameters:
+    ///   - root: 使用这个`UIViewController`的`UINavigationController`进行页面跳转
+    ///   - animated: 是否开启动画
+    ///   - completionHandler: 异步回调结果
     public func push(by root: UIViewController? = nil, animated: Bool = true, completionHandler: RouteCompletionHandler<UIViewController>? = nil) {
-        if let vc = self.viewController {
-            let root = root ?? self.getVisibleViewController()
+        if let vc = viewController {
+            let root = root ?? getVisibleViewController()
             root?.navigationController?.pushViewController(vc, animated: animated)
             completionHandler?(.success(vc))
             return
@@ -66,9 +75,14 @@ public final class RouteResponse {
         }
     }
 
+    /// 弹出页面
+    /// - Parameters:
+    ///   - root: 使用这个`UIViewController`进行弹出
+    ///   - animated: 是否开启动画
+    ///   - completionHandler: 异步回调结果
     public func present(by root: UIViewController? = nil, animated: Bool = true, completionHandler: RouteCompletionHandler<UIViewController>? = nil) {
-        if let vc = self.viewController {
-            let root = root ?? self.getVisibleViewController()
+        if let vc = viewController {
+            let root = root ?? getVisibleViewController()
             root?.present(vc, animated: animated, completion: {
                 completionHandler?(.success(vc))
             })
@@ -87,9 +101,15 @@ public final class RouteResponse {
         }
     }
 
+    /// 将页面包裹在`UINavigationController`中后弹出
+    /// - Parameters:
+    ///   - type: `UINavigationController`的类型
+    ///   - root: 使用这个`UIViewController`进行弹出
+    ///   - animated: 是否开启动画
+    ///   - completionHandler: 完成后异步回调
     public func presentWithNavigationController<N: UINavigationController>(_ type: N.Type, by root: UIViewController? = nil, animated: Bool = true, completionHandler: RouteCompletionHandler<UIViewController>? = nil) {
-        if let vc = self.viewController {
-            let root = root ?? self.getVisibleViewController()
+        if let vc = viewController {
+            let root = root ?? getVisibleViewController()
             root?.present(type.init(rootViewController: vc), animated: animated, completion: {
                 completionHandler?(.success(vc))
             })

Source/Router.swift

@@ -30,15 +30,10 @@ public extension Routable {
     }
 }
 
+
+/// 一个路由器可以通过解析链接获得一个指定的`UIViewController`实例
 public class UIViewControllerRouter {
     private var isInitialized = false
-    public var isNeedAutoRegister = false {
-        didSet {
-            if isNeedAutoRegister && !isInitialized {
-                autoRegisterIfNeed()
-            }
-        }
-    }
 
     static let shared = UIViewControllerRouter()
     private let urlRouter = URLRouter<UIViewController>()
@@ -55,14 +50,32 @@ public class UIViewControllerRouter {
         pthread_rwlock_destroy(&self.lock)
     }
 
-    func autoRegisterIfNeed() {
-        if isNeedAutoRegister {
+    
+    /// 如果路由未注册,自动进行注册
+    public func autoRegisterIfNeed() {
+        if !isInitialized {
             DispatchQueue(label: "com.router.register").async {
                 self.registerIfNeed()
             }
         }
     }
 
+    
+    /// 注册拦截器
+    /// - Parameter interceptors: 拦截器数组
+    public func register(interceptors: [RouteInterceptor]) {
+        let last = self.interceptors.removeLast()
+        self.interceptors.append(contentsOf: interceptors)
+        self.interceptors.append(last)
+    }
+
+    
+    /// 注册错误处理器
+    /// - Parameter handler: 一个错误处理器
+    public func registerErrorHandler(_ handler: RouteErrorHandling) {
+        errorHandler = handler
+    }
+
     func registerIfNeed() {
         if isInitialized {
             return
@@ -128,14 +141,4 @@ public class UIViewControllerRouter {
             completionHandler(.failure(error))
         }
     }
-
-    public func register(interceptors: [RouteInterceptor]) {
-        let last = self.interceptors.removeLast()
-        self.interceptors.append(contentsOf: interceptors)
-        self.interceptors.append(last)
-    }
-
-    public func registerErrorHandler(_ handler: RouteErrorHandling) {
-        errorHandler = handler
-    }
 }

Source/UIKit[Router].swift

@@ -9,17 +9,26 @@ import UIKit
 
 public extension UIApplication {
 
+    
+    /// 返回 `UIViewControllerRouter.shared`
     var router: UIViewControllerRouter {
         .shared
     }
-
+    
+    /// 通过链接进行页面跳转
+    /// - Parameter url: 路由链接
+    /// - Returns: 返回一个`RouteRequest`实例
     @inline(__always)
-    func route(url: URLComponentsConvertible) -> RouteResponse {
-        RouteResponse(url: url)
+    func route(url: URLComponentsConvertible) -> RouteRequest {
+        RouteRequest(url: url)
     }
 
-    func route(viewcontroller: UIViewController) -> RouteResponse {
-        let router = RouteResponse(url: String(describing: viewcontroller))
+    
+    /// 直接进行页面跳转
+    /// - Parameter viewcontroller: 想要跳转的`UIViewController`实例
+    /// - Returns: 返回一个`RouteRequest`实例
+    func route(viewcontroller: UIViewController) -> RouteRequest {
+        let router = RouteRequest(url: String(describing: viewcontroller))
         router.viewController = viewcontroller
         return router
     }

Source/URLComponentsConvertible.swift

@@ -7,11 +7,21 @@
 
 import Foundation
 
+/// Types adopting the `URLComponentsConvertible` protocol can be used to construct `URLComponents`s, which can then be used to route.
 public protocol URLComponentsConvertible {
+    /// 如果构造成功则返回一个 `URLComponents`,否则抛出异常.
+    ///
+    /// - Returns: 构造成功的`URLComponents`
+    /// - Throws:  一个`RouteError.badURL(url:)` 实例.
     func asURLComponents() throws -> URLComponents
 }
 
 extension String: URLComponentsConvertible {
+
+    /// 如果构造成功则返回一个 `URLComponents`,否则抛出异常.
+    ///
+    /// - Returns: 构造成功的`URLComponents`
+    /// - Throws:  一个`RouteError.badURL(url:)` 实例.
     public func asURLComponents() throws -> URLComponents {
         guard let components = URLComponents(string: trimmingCharacters(in: .whitespaces)) else {
             throw RouteError.badURL(url: self)
@@ -21,15 +31,22 @@ extension String: URLComponentsConvertible {
 }
 
 extension URL: URLComponentsConvertible {
+    /// 如果构造成功则返回一个 `URLComponents`,否则抛出异常.
+    ///
+    /// - Returns: 构造成功的`URLComponents`
+    /// - Throws:  一个`RouteError.badURL(url:)` 实例.
     public func asURLComponents() throws -> URLComponents {
         guard let components = URLComponents(url: self, resolvingAgainstBaseURL: true) else {
-            throw RouteError.badURL(url: self.absoluteString)
+            throw RouteError.badURL(url: absoluteString)
         }
         return components
     }
 }
 
 extension URLComponents: URLComponentsConvertible {
+    /// 如果构造成功则返回一个 `URLComponents`,否则抛出异常.
+    ///
+    /// - Returns: 构造成功的`URLComponents`
+    /// - Throws:  一个`RouteError.badURL(url:)` 实例.
     public func asURLComponents() throws -> URLComponents { self }
 }
-

Source/WebInterceptor.swift

@@ -8,9 +8,16 @@
 import SafariServices
 import UIKit
 
+
+/// 默认的网页拦截器,可以拦截`http`协议的链接,返回一个`SFSafariViewController`
 open class WebInterceptor: RouteInterceptor {
 
     public init() {}
+    
+    /// 收到路由事件后由此进行拦截,可以继承后修改实现.
+    /// - Parameters:
+    ///   - components: 一个`URLComponents`实例,由路由链接构造.
+    ///   - completionHandler: 拦截后由此进行回调.
     open func handle(components: URLComponents, completionHandler: @escaping RouteCompletionHandler<UIViewController?>) {
         if components.scheme?.hasPrefix("http") ?? false {
             if let url = components.url {