Add code documentation comments for all public APIs

Author: Jeehut

Images/Logo.png

@@ -1,9 +1,15 @@
 import Foundation
 
+/// The wrapper to configure LinksKit.
 public actor LinksKit {
    static var providerToken: String = ""
    static var linkSections: [LinkSection] = []
 
+   /// The main configuration method to be called upon app start to confure the contents of ``LinksView`` for use in settings/help menu.
+   ///
+   /// - Parameters:
+   ///   - providerToken: The `pt` query parameter of your app's campaign link. Same for all your apps, thus provided here on top level.
+   ///   - linkSections: The separate link sections you want to auto-render. Use one of the convenience helpers `.helpLinks`, `.socialMenus`, `.appMenus`, `.legalLinks`, or pass a custom ``LegalSection`` with the links/menus of your choice.
    public static func configure(providerToken: String, linkSections: [LinkSection]) {
       self.providerToken = providerToken
       self.linkSections = linkSections

Sources/LinksKit/LinksKit.swift

@@ -1,12 +1,29 @@
 import SwiftUI
 
+/// Represents a link with a title, system image, and URL.
+///
+/// Use this struct to create custom links or use the provided static methods for common link types.
 public struct Link: Identifiable {
    public let id: UUID = UUID()
    let title: String
    let systemImage: String
-
    let url: URL
 
+   /// Creates a new Link instance.
+   ///
+   /// - Parameters:
+   ///   - title: The display title for the link.
+   ///   - systemImage: The name of the system image to use as an icon.
+   ///   - url: The URL the link should open.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let customLink = Link(
+   ///     title: "Visit Our Website",
+   ///     systemImage: "globe",
+   ///     url: URL(string: "https://www.example.com")!
+   /// )
+   /// ```
    public init(title: String, systemImage: String, url: URL) {
       self.title = title
       self.systemImage = systemImage
@@ -15,6 +32,15 @@ public struct Link: Identifiable {
 }
 
 extension Link {
+   /// Creates a link to rate the app on the App Store.
+   ///
+   /// - Parameter id: The App Store ID of your app.
+   /// - Returns: A Link instance for rating the app.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let rateLink = Link.rateTheApp(id: "1234567890")
+   /// ```
    public static func rateTheApp(id: String) -> Self {
       Link(
          title: String(localized: "Rate the App", bundle: .module),
@@ -23,26 +49,81 @@ extension Link {
       )
    }
 
+   /// Creates a link to a Frequently Asked Questions (FAQ) page.
+   ///
+   /// - Parameter url: The URL of your FAQ page.
+   /// - Returns: A Link instance for the FAQ.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let faqLink = Link.frequentlyAskedQuestions(url: URL(string: "https://www.example.com/faq")!)
+   /// ```
    public static func frequentlyAskedQuestions(url: URL) -> Self {
       Link(title: String(localized: "Frequently Asked Questions (FAQ)", bundle: .module), systemImage: "questionmark.bubble", url: url)
    }
 
+   /// Creates a link to contact support via email.
+   ///
+   /// - Parameter email: The support email address.
+   /// - Returns: A Link instance for contacting support.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let supportLink = Link.contactSupport(email: "support@example.com")
+   /// ```
    public static func contactSupport(email: String) -> Self {
       Link(title: String(localized: "Contact Support", bundle: .module), systemImage: "envelope", url: URL(string: "mailto:\(email)")!)
    }
 
+   /// Creates a link to the privacy policy.
+   ///
+   /// - Parameter url: The URL of your privacy policy.
+   /// - Returns: A Link instance for the privacy policy.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let privacyLink = Link.privacyPolicy(url: URL(string: "https://www.example.com/privacy")!)
+   /// ```
    public static func privacyPolicy(url: URL) -> Self {
       Link(title: String(localized: "Privacy Policy", bundle: .module), systemImage: "lock.shield", url: url)
    }
 
+   /// Creates a link to the standard App Store Terms and Conditions.
+   ///
+   /// - Returns: A Link instance for the App Store Terms and Conditions.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let termsLink = Link.appStoreTermsAndConditions()
+   /// ```
    public static func appStoreTermsAndConditions() -> Self {
       .termsAndConditions(url: URL(string: "https://www.apple.com/legal/internet-services/itunes/dev/stdeula/")!)
    }
 
+   /// Creates a link to custom Terms and Conditions.
+   ///
+   /// - Parameter url: The URL of your Terms and Conditions.
+   /// - Returns: A Link instance for the Terms and Conditions.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let customTermsLink = Link.termsAndConditions(url: URL(string: "https://www.example.com/terms")!)
+   /// ```
    public static func termsAndConditions(url: URL) -> Self {
       Link(title: String(localized: "Terms and Conditions", bundle: .module), systemImage: "text.book.closed", url: url)
    }
 
+   /// Creates a link to follow the app on a social media platform.
+   ///
+   /// - Parameters:
+   ///   - socialPlatform: The social media platform.
+   ///   - handle: The app's handle or username on the platform.
+   /// - Returns: A Link instance for following the app on social media.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let twitterFollowLink = Link.followUsOn(socialPlatform: .twitter, handle: "YourAppHandle")
+   /// ```
    public static func followUsOn(socialPlatform: SocialPlatform, handle: String) -> Self {
       Link(
          title: String(localized: "Follow us on \(socialPlatform.description)"),
@@ -51,6 +132,17 @@ extension Link {
       )
    }
 
+   /// Creates a link to the developer's profile on a social media platform.
+   ///
+   /// - Parameters:
+   ///   - socialPlatform: The social media platform.
+   ///   - handle: The developer's handle or username on the platform.
+   /// - Returns: A Link instance for the developer's social media profile.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let devTwitterLink = Link.developerOn(socialPlatform: .twitter, handle: "YourDevHandle")
+   /// ```
    public static func developerOn(socialPlatform: SocialPlatform, handle: String) -> Self {
       Link(
          title: String(localized: "Developer on \(socialPlatform.description)"),
@@ -59,6 +151,17 @@ extension Link {
       )
    }
 
+   /// Creates a link to the app's profile on a social media platform.
+   ///
+   /// - Parameters:
+   ///   - socialPlatform: The social media platform.
+   ///   - handle: The app's handle or username on the platform.
+   /// - Returns: A Link instance for the app's social media profile.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let appInstagramLink = Link.appOn(socialPlatform: .instagram, handle: "YourAppHandle")
+   /// ```
    public static func appOn(socialPlatform: SocialPlatform, handle: String) -> Self {
       Link(
          title: String(localized: "App on \(socialPlatform.description)"),
@@ -67,6 +170,24 @@ extension Link {
       )
    }
 
+   /// Creates a link to one of your own apps on the App Store.
+   ///
+   /// - Parameters:
+   ///   - id: The App Store ID of the app.
+   ///   - name: The name of the app.
+   ///   - systemImage: The system image name to use as an icon.
+   ///   - campaignToken: An optional campaign token for tracking. Defaults to the main bundle identifier.
+   /// - Returns: A Link instance for your own app.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let myOtherAppLink = Link.ownApp(
+   ///     id: "1234567890",
+   ///     name: "My Other App",
+   ///     systemImage: "star.circle",
+   ///     campaignToken: "myOtherApp"
+   /// )
+   /// ```
    public static func ownApp(
       id: String,
       name: String,
@@ -80,6 +201,26 @@ extension Link {
       )
    }
 
+   /// Creates a link to a friend's app on the App Store.
+   ///
+   /// - Parameters:
+   ///   - id: The App Store ID of the app.
+   ///   - name: The name of the app.
+   ///   - systemImage: The system image name to use as an icon.
+   ///   - providerToken: An optional provider token for the app's developer.
+   ///   - campaignToken: An optional campaign token for tracking. Defaults to the main bundle identifier.
+   /// - Returns: A Link instance for a friend's app.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let friendAppLink = Link.friendsApp(
+   ///     id: "0987654321",
+   ///     name: "Friend's Cool App",
+   ///     systemImage: "paintbrush",
+   ///     providerToken: "123456",
+   ///     campaignToken: "friendCoolApp"
+   /// )
+   /// ```
    public static func friendsApp(
       id: String,
       name: String,
@@ -100,6 +241,5 @@ extension Link {
             url: URL(string: "https://apps.apple.com/app/id\(id)?ct=\(campaignToken)&mt=8")!
          )
       }
-
    }
 }

Sources/LinksKit/Model/Link.swift

@@ -1,12 +1,34 @@
 import Foundation
 
+/// Represents a menu containing multiple link sections.
+///
+/// Use this struct to create grouped links that can be displayed in a submenu.
 public struct LinkMenu: Identifiable {
    public let id: UUID = UUID()
    let title: String
    let systemImage: String
-
    let linkSections: [LinkSection]
 
+   /// Creates a new LinkMenu instance.
+   ///
+   /// - Parameters:
+   ///   - title: The display title for the menu.
+   ///   - systemImage: The name of the system image to use as an icon.
+   ///   - linkSections: An array of LinkSection instances to include in the menu.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let customMenu = LinkMenu(
+   ///     title: "Social Media",
+   ///     systemImage: "network",
+   ///     linkSections: [
+   ///         LinkSection(entries: [
+   ///             .link(Link.followUsOn(socialPlatform: .twitter, handle: "YourAppHandle")),
+   ///             .link(Link.followUsOn(socialPlatform: .instagram, handle: "YourAppHandle"))
+   ///         ])
+   ///     ]
+   /// )
+   /// ```
    public init(title: String, systemImage: String, linkSections: [LinkSection]) {
       self.title = title
       self.systemImage = systemImage
@@ -15,6 +37,18 @@ public struct LinkMenu: Identifiable {
 }
 
 extension LinkMenu {
+   /// Creates a menu for following the app on various social media platforms.
+   ///
+   /// - Parameter links: An array of Link instances for different social media platforms.
+   /// - Returns: A LinkMenu instance for following the app.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let followAppMenu = LinkMenu.followTheApp(links: [
+   ///     Link.followUsOn(socialPlatform: .twitter, handle: "YourAppHandle"),
+   ///     Link.followUsOn(socialPlatform: .instagram, handle: "YourAppHandle")
+   /// ])
+   /// ```
    public static func followTheApp(links: [Link]) -> Self {
       LinkMenu(
          title: String(localized: "Follow the App", bundle: .module),
@@ -23,6 +57,18 @@ extension LinkMenu {
       )
    }
 
+   /// Creates a menu for following the developer on various social media platforms.
+   ///
+   /// - Parameter links: An array of Link instances for different social media platforms.
+   /// - Returns: A LinkMenu instance for following the developer.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let followDevMenu = LinkMenu.followTheDeveloper(links: [
+   ///     Link.developerOn(socialPlatform: .twitter, handle: "YourDevHandle"),
+   ///     Link.developerOn(socialPlatform: .github, handle: "YourDevHandle")
+   /// ])
+   /// ```
    public static func followTheDeveloper(links: [Link]) -> Self {
       LinkMenu(
          title: String(localized: "Follow the Developer", bundle: .module),
@@ -31,6 +77,23 @@ extension LinkMenu {
       )
    }
 
+   /// Creates a menu for showcasing more apps from the developer.
+   ///
+   /// - Parameter linkSections: An array of LinkSection instances, each potentially representing a category of apps.
+   /// - Returns: A LinkMenu instance for more apps from the developer.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let moreAppsMenu = LinkMenu.moreAppsFromDeveloper(linkSections: [
+   ///     LinkSection(title: "Productivity Apps", entries: [
+   ///         .link(Link.ownApp(id: "1234567890", name: "Todo Master", systemImage: "checklist")),
+   ///         .link(Link.ownApp(id: "0987654321", name: "Focus Timer", systemImage: "timer"))
+   ///     ]),
+   ///     LinkSection(title: "Entertainment Apps", entries: [
+   ///         .link(Link.ownApp(id: "1122334455", name: "Puzzle Quest", systemImage: "puzzle"))
+   ///     ])
+   /// ])
+   /// ```
    public static func moreAppsFromDeveloper(linkSections: [LinkSection]) -> Self {
       LinkMenu(
          title: String(localized: "More apps from Developer", bundle: .module),
@@ -39,6 +102,20 @@ extension LinkMenu {
       )
    }
 
+   /// Creates a menu for showcasing related apps that users might like.
+   ///
+   /// - Parameter linkSections: An array of LinkSection instances, each potentially representing a category of related apps.
+   /// - Returns: A LinkMenu instance for related apps.
+   ///
+   /// Example usage:
+   /// ```swift
+   /// let relatedAppsMenu = LinkMenu.relatedAppsYouMightLike(linkSections: [
+   ///     LinkSection(title: "Similar Productivity Apps", entries: [
+   ///         .link(Link.friendsApp(id: "2233445566", name: "Task Pro", systemImage: "list.bullet", providerToken: "654321")),
+   ///         .link(Link.friendsApp(id: "3344556677", name: "Time Tracker", systemImage: "stopwatch", providerToken: "765432"))
+   ///     ])
+   /// ])
+   /// ```
    public static func relatedAppsYouMightLike(linkSections: [LinkSection]) -> Self {
       LinkMenu(
          title: String(localized: "Related apps you might Like", bundle: .module),