From ba16f1e15b3152e98f6e11bedfec183349be4459 Mon Sep 17 00:00:00 2001 From: KEL Date: Fri, 30 Jun 2023 05:00:43 +1200 Subject: [PATCH] [chore] docs (#28) --- .github/workflows/documentation.yml | 44 +++++++++++++++++++ .gitignore | 1 + Package.swift | 1 + README.md | 5 +++ Sources/XConfigs/Protocols/ConfigInfo.swift | 1 + .../Protocols/InAppConfigUpdateDelegate.swift | 1 + .../XConfigs/Protocols/KeyValueProvider.swift | 1 + .../XConfigs/Protocols/KeyValueStore.swift | 1 + .../RawStringValueRepresentable.swift | 1 + Sources/XConfigs/Services/LogicHandler.swift | 1 + .../XConfigs/UseCases/XConfigUseCase.swift | 7 ++- Sources/XConfigs/XConfigs.swift | 3 ++ 12 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/documentation.yml diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..602f4e1 --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,44 @@ +name: Documentation + +on: + push: + branches: + - "main" + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: true + +jobs: + build: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }}documentation/xconfigs + runs-on: macos-latest + steps: + - uses: actions/checkout@v3 + - name: Generate Documentation + run: | + swift package --allow-writing-to-directory ./docs \ + generate-documentation --target XConfigs \ + --disable-indexing \ + --transform-for-static-hosting \ + --output-path ./docs \ + --hosting-base-path XConfigs + + - name: Setup Pages + uses: actions/configure-pages@v3 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: './docs' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v2 diff --git a/.gitignore b/.gitignore index bb460e7..59e2947 100644 --- a/.gitignore +++ b/.gitignore @@ -5,3 +5,4 @@ xcuserdata/ DerivedData/ .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata +Package.resolved diff --git a/Package.swift b/Package.swift index a412f56..7dec4e7 100644 --- a/Package.swift +++ b/Package.swift @@ -19,6 +19,7 @@ let package = Package( .package(url: "https://github.com/ra1028/DiffableDataSources", from: "0.5.0"), .package(url: "https://github.com/michaelhenry/Prettier.swift", from: "1.1.1"), .package(url: "https://github.com/raspu/Highlightr", from: "2.1.2"), + .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.3.0"), ], targets: [ .target( diff --git a/README.md b/README.md index 9c5151a..282a471 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ - [Introduction](#introduction) - [Getting Started](#getting-started) - [How to use](#how-to-use) +- [Documentation](#-documentation) - [Example](#example) - [Other Related](#other-related) - [License](#license) @@ -54,6 +55,10 @@ Eg. #endif ``` +## 📄 Documentation + +Please refer to [XConfigs's docs](https://michaelhenry.github.io/XConfigs/documentation/xconfigs/). + ## Example Similar with logger tool such as [swift-log](https://github.com/apple/swift-log), You can simply create a single global variable or just a singleton, as long as the it conforms to [XConfigSpec](Sources/XConfigs/Protocols/XConfigsSpec.swift)ification and then use the `@XConfig` property wrapper inside it. diff --git a/Sources/XConfigs/Protocols/ConfigInfo.swift b/Sources/XConfigs/Protocols/ConfigInfo.swift index 8778b78..a69a690 100644 --- a/Sources/XConfigs/Protocols/ConfigInfo.swift +++ b/Sources/XConfigs/Protocols/ConfigInfo.swift @@ -1,5 +1,6 @@ import Foundation +/// A protocol for parsing a configuration spec file (`XConfigsSpec`). public protocol ConfigInfo { var configKey: String { get } var displayName: String? { get } diff --git a/Sources/XConfigs/Protocols/InAppConfigUpdateDelegate.swift b/Sources/XConfigs/Protocols/InAppConfigUpdateDelegate.swift index 881cbc6..1a8404d 100644 --- a/Sources/XConfigs/Protocols/InAppConfigUpdateDelegate.swift +++ b/Sources/XConfigs/Protocols/InAppConfigUpdateDelegate.swift @@ -1,5 +1,6 @@ import Foundation +/// A delegate that listen to the key-value changed done inside the in-app config screen. public protocol InAppConfigUpdateDelegate { func configWillUpdate(key: String, value: RawStringValueRepresentable, store: KeyValueStore) } diff --git a/Sources/XConfigs/Protocols/KeyValueProvider.swift b/Sources/XConfigs/Protocols/KeyValueProvider.swift index 426eb32..6b89e8b 100644 --- a/Sources/XConfigs/Protocols/KeyValueProvider.swift +++ b/Sources/XConfigs/Protocols/KeyValueProvider.swift @@ -1,5 +1,6 @@ import Foundation +/// A protocol for providing key value. public protocol KeyValueProvider { func get(for key: String) -> Value? } diff --git a/Sources/XConfigs/Protocols/KeyValueStore.swift b/Sources/XConfigs/Protocols/KeyValueStore.swift index d05e4ef..a24d374 100644 --- a/Sources/XConfigs/Protocols/KeyValueStore.swift +++ b/Sources/XConfigs/Protocols/KeyValueStore.swift @@ -1,5 +1,6 @@ import Foundation +/// A protocol for storing key values when the in-app modification is enabled. public protocol KeyValueStore { func get(for key: String) -> Value? func set(value: Value, for key: String) diff --git a/Sources/XConfigs/Protocols/RawStringValueRepresentable.swift b/Sources/XConfigs/Protocols/RawStringValueRepresentable.swift index 41110fb..f95e860 100644 --- a/Sources/XConfigs/Protocols/RawStringValueRepresentable.swift +++ b/Sources/XConfigs/Protocols/RawStringValueRepresentable.swift @@ -1,5 +1,6 @@ import Foundation +/// A protocol for representing any object or data type into a string or vise versa via `rawString` property. public protocol RawStringValueRepresentable: Codable { var rawString: String { get } diff --git a/Sources/XConfigs/Services/LogicHandler.swift b/Sources/XConfigs/Services/LogicHandler.swift index 09b14ea..29a9193 100644 --- a/Sources/XConfigs/Services/LogicHandler.swift +++ b/Sources/XConfigs/Services/LogicHandler.swift @@ -10,6 +10,7 @@ public struct ValueWithPermission { } } +/// A protocol that handles the actual logic for the configuration. public protocol XConfigsLogicHandler { func handle(isInAppModificationEnabled: Bool, key: String, defaultValue: Value, group: XConfigGroup, keyValueProvider: KeyValueProvider, keyValueStore: KeyValueStore?) -> ValueWithPermission } diff --git a/Sources/XConfigs/UseCases/XConfigUseCase.swift b/Sources/XConfigs/UseCases/XConfigUseCase.swift index 86713db..22797bd 100644 --- a/Sources/XConfigs/UseCases/XConfigUseCase.swift +++ b/Sources/XConfigs/UseCases/XConfigUseCase.swift @@ -3,6 +3,7 @@ import Foundation public class XConfigUseCase { private let isInAppModificationEnabledKey = "XConfigs.Debug.isInAppModificationEnabled" + /// Determine if the in-app modification is enabled. var isInAppModificationEnabled: Bool { get { keyValueStore?.get(for: isInAppModificationEnabledKey) ?? false @@ -19,7 +20,7 @@ public class XConfigUseCase { private let logicHandler: XConfigsLogicHandler private let updateDelegate: InAppConfigUpdateDelegate? - // To update the local kv store and remote kv provider, please use the assigned method for it. + /// To update the local kv store and remote kv provider, please use the assigned method for it. init(spec: XConfigsSpec.Type, keyValueProvider: KeyValueProvider, logicHandler: XConfigsLogicHandler, keyValueStore: KeyValueStore?, updateDelegate: InAppConfigUpdateDelegate?) { configsSpec = spec self.keyValueProvider = keyValueProvider @@ -28,22 +29,26 @@ public class XConfigUseCase { self.updateDelegate = updateDelegate } + /// Get the information from the ConfigSpec. func getConfigs() -> [ConfigInfo] { let instance = configsSpec.init() let mirror = Mirror(reflecting: instance) return mirror.children.compactMap { $0.value as? ConfigInfo } } + /// Get the Value of a particular key. func get(for key: String, defaultValue: Value, group: XConfigGroup) -> ValueWithPermission { logicHandler.handle(isInAppModificationEnabled: isInAppModificationEnabled, key: key, defaultValue: defaultValue, group: group, keyValueProvider: keyValueProvider, keyValueStore: keyValueStore) } + /// Set the Value of a particular key. func set(value: Value, for key: String) { guard isInAppModificationEnabled, let store = keyValueStore else { return } updateDelegate?.configWillUpdate(key: key, value: value, store: store) keyValueStore?.set(value: value, for: key) } + /// Reset the store (needed for the in-app modification). func reset() { guard isInAppModificationEnabled else { return } getConfigs().forEach { diff --git a/Sources/XConfigs/XConfigs.swift b/Sources/XConfigs/XConfigs.swift index 4acc3b2..1460f4a 100644 --- a/Sources/XConfigs/XConfigs.swift +++ b/Sources/XConfigs/XConfigs.swift @@ -7,6 +7,7 @@ import Foundation internal var defaultConfigUseCase: XConfigUseCase! public enum XConfigs { + /// Use this method the configure the XConfigs into your app. public static func configure( with spec: XConfigsSpec.Type, keyValueProvider: KeyValueProvider, @@ -32,6 +33,8 @@ public enum XConfigs { try vc.present(configsViewController().wrapInsideNavVC(), animated: animated, completion: nil) } #endif + + /// A method to allow in-app modification or not. public static func setInAppModification(enable: Bool) throws { guard defaultConfigUseCase.keyValueStore != nil else { throw ConfigError.inAppModificationIsNotAllowed } defaultConfigUseCase.isInAppModificationEnabled = enable