Update Documentation in Conformance to the Documentation Guide (#25)

<!--

This source file is part of the Stanford Spezi open-source project

SPDX-FileCopyrightText: 2022 Stanford University and the project authors
(see CONTRIBUTORS.md)

SPDX-License-Identifier: MIT

-->

# Update Documentation in Conformance to the Documentation Guide

## ♻️ Current situation & Problem
See issue #16.

## 📝 Code of Conduct & Contributing Guidelines 

By submitting creating this pull request, you agree to follow our [Code
of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md):
- [X] I agree to follow the [Code of
Conduct](https://github.com/StanfordSpezi/.github/blob/main/CODE_OF_CONDUCT.md)
and [Contributing
Guidelines](https://github.com/StanfordSpezi/.github/blob/main/CONTRIBUTING.md).

---------

Co-authored-by: Paul Schmiedmayer <PSchmiedmayer@users.noreply.github.com>

README.md

@@ -16,13 +16,134 @@ SPDX-License-Identifier: MIT
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FStanfordSpezi%2FSpeziOnboarding%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/StanfordSpezi/SpeziOnboarding)
 [![](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2FStanfordSpezi%2FSpeziOnboarding%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/StanfordSpezi/SpeziOnboarding)
 
-The Spezi Onboarding module provides user interface components to onboard a user to an application including the possibility to retrieve consent for a study participation.
+Provides UI components for onboarding and consent.
+
+
+## Overview
+
+The Spezi Onboarding module provides user interface components to onboard a user to an application, including the possibility of retrieving consent for study participation.
 
-<p float="left">
- <img width="250" alt="A screen displaying welcome view." src="Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/OnboardingView.png">
- <img width="250" alt="A screen showing an sequencial onboarding view." src="Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/SequentialOnboardingView.png">
- <img width="250" alt="A screen displaying the consent view." src="Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/ConsentView.png">
-</p>
+|![Screenshot displaying the onboarding view.](Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/OnboardingView.png#gh-light-mode-only) ![Screenshot displaying the onboarding view.](Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/OnboardingView~dark.png#gh-dark-mode-only)|![Screenshot displaying the sequential onboarding view.](Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/SequentialOnboardingView.png#gh-light-mode-only) ![Screenshot displaying the sequential onboarding view.](Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/SequentialOnboardingView~dark.png#gh-dark-mode-only)|![Screenshot displaying the consent view.](Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/ConsentView.png#gh-light-mode-only) ![Screenshot displaying the consent view.](Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/ConsentView~dark.png#gh-dark-mode-only)
+|:--:|:--:|:--:|
+|[`OnboardingView`](https://swiftpackageindex.com/stanfordspezi/spezionboarding/documentation/spezionboarding/onboardingview)|[`SequentialOnboardingView`](https://swiftpackageindex.com/stanfordspezi/spezionboarding/documentation/spezionboarding/sequentialonboardingview)|[`ConsentView`](https://swiftpackageindex.com/stanfordspezi/spezionboarding/documentation/spezionboarding/consentview)|
+
+
+## Setup
+
+### Add Spezi Onboarding as a Dependency
+
+You need to add the Spezi Onboarding Swift package to
+[your app in Xcode](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app#) or
+[Swift package](https://developer.apple.com/documentation/xcode/creating-a-standalone-swift-package-with-xcode#Add-a-dependency-on-another-Swift-package).
+
+
+## Examples
+
+### Onboarding View
+
+The [`OnboardingView`](https://swiftpackageindex.com/stanfordspezi/spezionboarding/documentation/spezionboarding/onboardingview) allows you to separate information into areas on a screen, each with a title, description, and icon.
+
+```swift
+import SpeziOnboarding
+import SwiftUI
+
+
+struct OnboardingViewExample: View {
+    var body: some View {
+        OnboardingView(
+            title: "Welcome",
+            subtitle: "This is an example onboarding view",
+            areas: [
+                .init(
+                    icon: Image(systemName: "tortoise.fill"), 
+                    title: "Tortoise", 
+                    description: "A Tortoise!"
+                ),
+                .init(
+                    icon: Image(systemName: "lizard.fill"), 
+                    title: "Lizard", 
+                    description: "A Lizard!"
+                ),
+                .init(
+                    icon: Image(systemName: "tree.fill"), 
+                    title: "Tree", 
+                    description: "A Tree!"
+                )
+            ],
+            actionText: "Learn More",
+            action: {
+                // Action to perform when the user taps the action button.
+            }
+        )
+    }
+}
+```
+
+
+### Sequential Onboarding View
+
+The [`SequentialOnboardingView`](https://swiftpackageindex.com/stanfordspezi/spezionboarding/documentation/spezionboarding/sequentialonboardingview) allows you to display information step-by-step with each additional area appearing when the user taps the `Continue` button.
+
+```swift
+import SpeziOnboarding
+import SwiftUI
+
+
+struct SequentialOnboardingViewExample: View {
+    var body: some View {
+        SequentialOnboardingView(
+            title: "Things to know",
+            subtitle: "And you should pay close attention ...",
+            content: [
+                .init(
+                    title: "A thing to know", 
+                    description: "This is a first thing that you should know; read carefully!"
+                ),
+                .init(
+                    title: "Second thing to know", 
+                    description: "This is a second thing that you should know; read carefully!"
+                ),
+                .init(
+                    title: "Third thing to know", 
+                    description: "This is a third thing that you should know; read carefully!"
+                )
+            ],
+            actionText: "Continue"
+        ) {
+            // Action to perform when the user has viewed all the steps
+        }
+    }
+}
+```
+
+
+### Consent View
+
+The [`ConsentView`](https://swiftpackageindex.com/stanfordspezi/spezionboarding/documentation/spezionboarding/consentview) can be used to allow your users to read and agree to a document, e.g., a consent document for a research study or a terms and conditions document for an app. The document can be signed using a family and given name and a hand-drawn signature. 
+
+The following example demonstrates how the [`ConsentView`](https://swiftpackageindex.com/stanfordspezi/spezionboarding/documentation/spezionboarding/consentview) shown above is constructed by providing a header, markdown content encoded as a [UTF8](https://www.swift.org/blog/utf8-string/) [`Data`](https://developer.apple.com/documentation/foundation/data) instance (which may be provided asynchronously), and an action that should be performed once the consent has been given.
+
+```swift
+import SpeziOnboarding
+import SwiftUI
+
+
+struct ConsentViewExample: View {
+    var body: some View {
+        ConsentView(
+            header: {
+                OnboardingTitleView(title: "Consent", subtitle: "Version 1.0")
+            },
+            asyncMarkdown: {
+                Data("This is a *markdown* **example**".utf8)
+            },
+            action: {
+                // Action to perform once the user has given their consent
+            }
+        )
+    }
+}
+```
 
 For more information, please refer to the [API documentation](https://swiftpackageindex.com/StanfordSpezi/SpeziOnboarding/documentation).
 

Sources/SpeziOnboarding/ConsentView.swift

@@ -13,8 +13,8 @@ import SwiftUI
 
 /// The ``ConsentView`` allows the display of markdown-based documents that can be signed using a family and given name and a hand drawn signature.
 ///
-/// The ``ConsentView`` provides a convenience initializer with a provided action view using an ``OnboardingActionsView`` (``ConsentView/init(header:asyncMarkdown:footer:action:)``)
-/// or a more customized ``ConsentView/init(contentView:actionView:)`` initializer with a custom-provided content and action view.
+/// The ``ConsentView`` provides a convenience initializer with a provided action view using an ``OnboardingActionsView`` (``ConsentView/init(header:asyncMarkdown:footer:action:givenNameField:familyNameField:)``)
+/// or a more customized ``ConsentView/init(contentView:actionView:givenNameField:familyNameField:)`` initializer with a custom-provided content and action view.
 ///
 /// ```swift
 /// ConsentView(

Sources/SpeziOnboarding/OnboardingFlow/OnboardingStack.swift

@@ -61,11 +61,11 @@ public struct OnboardingStack: View {
     }
 
 
-    /// A ``OnboardingStack`` is defined by the ``_OnboardingFlowViewCollection`` resulting from the evaluation of the ``OnboardingViewBuilder`` result builder as well as an boolean `Binding` that is set to true when the onboarding flow is completed.
+    /// A ``OnboardingStack`` is defined by the passed in views defined by the view builder as well as an boolean `Binding` that is set to true when the onboarding flow is completed.
     /// - Parameters:
     ///   - onboardingFlowComplete: An optional SwiftUI `Binding` that is automatically set to true by the ``OnboardingNavigationPath`` once the onboarding flow is completed. Can be used to conditionally show/hide the ``OnboardingStack``.
     ///   - startAtStep: An optional SwiftUI (Onboarding) `View` type indicating the first to-be-shown step of the onboarding flow.
-    ///   - content: The SwiftUI (Onboarding) `View`s that are part of the onboarding flow. You can define the `View`s using the ``OnboardingViewBuilder`` result builder.
+    ///   - content: The SwiftUI (Onboarding) `View`s that are part of the onboarding flow. You can define the `View`s using the onboarding view builder.
     public init(
         onboardingFlowComplete: Binding<Bool>? = nil,
         startAtStep: (any View.Type)? = nil,

Sources/SpeziOnboarding/OnboardingFlow/OnboardingViewBuilder.swift

@@ -12,6 +12,7 @@ import SwiftUI
 
 /// A result builder used to aggregate multiple SwiftUI `View`s within the ``OnboardingStack``
 @resultBuilder
+@_documentation(visibility: internal)
 public enum OnboardingViewBuilder {
     /// If declared, provides contextual type information for statement expressions to translate them into partial results.
     public static func buildExpression(_ expression: any View) -> [any View] {

Sources/SpeziOnboarding/SpeziOnboarding.docc/DisplayingInformation.md

@@ -14,7 +14,7 @@ Display information to your user during an onboarding flow.
 
 ## OnboardingView
 
-The ``OnboardingView`` allows you to separate information into areas on a screen, each with a title, description, and icon.
+The <doc:OnboardingView> allows you to separate information into areas on a screen, each with a title, description, and icon.
 
 ![OnboardingView](OnboardingView.png)
 
@@ -45,11 +45,12 @@ OnboardingView(
     action: {
         // Action to perform when the user taps the action button.
     }
+)
 ```
 
 ## SequentialOnboardingView
 
-The ``SequentialOnboardingView`` allows you to display information step-by-step with each additional area appearing when the user taps the `Continue` button.
+The <doc:SequentialOnboardingView> allows you to display information step-by-step, with each additional area appearing when the user taps the `Continue` button.
 
 ![SequentialOnboardingView](SequentialOnboardingView.png)
 
@@ -62,15 +63,15 @@ SequentialOnboardingView(
     content: [
         .init(
             title: "A thing to know", 
-            description: "This is a first thing that you should know, read carefully!"
+            description: "This is a first thing that you should know; read carefully!"
         ),
         .init(
             title: "Second thing to know", 
-            description: "This is a second thing that you should know, read carefully!"
+            description: "This is a second thing that you should know; read carefully!"
         ),
         .init(
             title: "Third thing to know", 
-            description: "This is a third thing that you should know, read carefully!"
+            description: "This is a third thing that you should know; read carefully!"
         )
     ],
     actionText: "Continue"
@@ -83,5 +84,5 @@ SequentialOnboardingView(
 
 ### Views
 
-- ``OnboardingView``
-- ``SequentialOnboardingView``
+- <doc:OnboardingView>
+- <doc:SequentialOnboardingView>

Sources/SpeziOnboarding/SpeziOnboarding.docc/ObtainingUserConsent.md

@@ -14,11 +14,11 @@ Present your user a consent document to read and sign.
 
 ### Obtaining User Consent
 
-The ``ConsentView`` can be used to allow your users to read and agree to a document, e.g. a consent document for a research study or a terms and conditions document for an app. The document can be signed using a family and given name, and a hand drawn signature. 
+The ``ConsentView`` can allow users to read and agree to a document, e.g., a consent document for a research study or a terms and conditions document for an app. The document can be signed using a family and given name and a hand-drawn signature. 
 
 ![ConsentView](ConsentView.png)
 
-The following example demonstrates how the ``ConsentView`` shown above is constructed by providing a header, markdown content encoded as a UTF8 `Data` instance (which may be provided asynchronously), and an action that should be performed once the consent has been given.
+The following example demonstrates how the ``ConsentView`` shown above is constructed by providing a header, markdown content encoded as a [UTF8](https://www.swift.org/blog/utf8-string/) [`Data`](https://developer.apple.com/documentation/foundation/data) instance (which may be provided asynchronously), and an action that should be performed once the consent has been given.
 
 ```swift
 ConsentView(
@@ -34,6 +34,7 @@ ConsentView(
 )
 ```
 
+
 ## Topics
 
 ### Views

Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/ConsentView~dark.png.license

@@ -0,0 +1,9 @@
+<!--
+
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT
+
+-->

Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/OnboardingView~dark.png.license

@@ -0,0 +1,9 @@
+<!--
+
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT
+
+-->

Sources/SpeziOnboarding/SpeziOnboarding.docc/Resources/SequentialOnboardingView~dark.png.license

@@ -0,0 +1,9 @@
+<!--
+
+This source file is part of the Stanford Spezi open-source project
+
+SPDX-FileCopyrightText: 2022 Stanford University and the project authors (see CONTRIBUTORS.md)
+
+SPDX-License-Identifier: MIT
+
+-->