Enhance DocC-compatible inline docs for future documentation (Issue #866)

Sources/mas/Commands/Account.swift

@@ -9,6 +9,15 @@ internal import ArgumentParser
 
 extension MAS {
 	/// Outputs the Apple Account signed in to the Mac App Store.
+	/// Outputs the Apple Account signed in to the Mac App Store.
+	///
+	/// > Warning:
+	/// > This command is **not supported on macOS 12 (Monterey) or newer** due to Apple changing private frameworks.
+	/// > See [Issue #417](https://github.com/mas-cli/mas/issues/417) for more details.
+	///
+	/// > Note:
+	/// > mas uses private Apple frameworks for this command, which are undocumented and subject to change.
+	/// > Functionality may break without notice in future macOS versions.
 	struct Account: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Output the Apple Account signed in to the Mac App Store"

Sources/mas/Commands/Config.swift

@@ -12,7 +12,20 @@ private var unknown: String { "unknown" }
 private var sysCtlByName: String { "sysctlbyname" }
 
 extension MAS {
-	/// Outputs mas config & related system info.
+	/// Displays detailed configuration and environment information for `mas`.
+	///
+	/// This includes version info, architecture, installation method, build revision,
+	/// Swift driver version, macOS version, CPU, and region settings.
+	///
+	/// This command is particularly useful for users and developers who need
+	/// to inspect runtime environment details — for example, when reporting issues or verifying setup.
+	///
+	/// Use `--markdown` to output results in a Markdown-friendly format.
+	///
+	/// Example:
+	/// ```bash
+	/// mas config --markdown
+	/// ```
 	struct Config: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Output mas config & related system info"

Sources/mas/Commands/Home.swift

@@ -9,11 +9,23 @@ internal import ArgumentParser
 private import Foundation
 
 extension MAS {
-	/// Opens Mac App Store app pages in the default web browser.
+	/// Opens the App Store page for one or more apps in your default web browser.
 	///
-	/// Uses the iTunes Lookup API:
+	/// This command uses the public iTunes Search API to fetch the app’s page URL,
+	/// and then opens the page in your system’s default browser.
 	///
-	/// https://performance-partners.apple.com/search-api
+	/// This can be useful for quickly viewing app details, screenshots, or reviews in the App Store.
+	///
+	/// > Note: This command does not output any information to the terminal.
+	/// > It simply launches your web browser.
+	///
+	/// Example:
+	/// ```bash
+	/// mas home 497799835
+	/// ```
+	///
+	/// See also:
+	/// [iTunes Search API](https://performance-partners.apple.com/search-api)
 	struct Home: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Open Mac App Store app pages in the default web browser"

Sources/mas/Commands/Info.swift

@@ -9,11 +9,41 @@ internal import ArgumentParser
 private import Foundation
 
 extension MAS {
-	/// Outputs app information from the Mac App Store.
+	/// Displays detailed information about apps from the Mac App Store.
 	///
-	/// Uses the iTunes Lookup API:
+	/// This command uses the public iTunes Search API to retrieve rich metadata
+	/// for each specified app ID, including:
+	/// - App name
+	/// - Developer
+	/// - Release date
+	/// - Minimum OS version
+	/// - Size
+	/// - App Store URL
 	///
-	/// https://performance-partners.apple.com/search-api
+	/// This can be useful when investigating apps before installing them, or
+	/// when confirming information such as version compatibility or publisher.
+	///
+	/// > Tip:
+	/// > You can combine this with `mas search` to look up the ID, and then use `mas info`
+	/// > to view full details.
+	///
+	/// Example:
+	/// ```bash
+	/// mas info 497799835
+	/// ```
+	///
+	/// Output:
+	/// ```
+	/// Xcode 16.0 [Free]
+	/// By: Apple Inc.
+	/// Released: 2024-09-16
+	/// Minimum OS: 14.5
+	/// Size: 2.98 GB
+	/// From: https://apps.apple.com/us/app/xcode/id497799835?mt=12&uo=4
+	/// ```
+	///
+	/// See also:
+	/// [iTunes Search API](https://performance-partners.apple.com/search-api)
 	struct Info: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Output app information from the Mac App Store"

Sources/mas/Commands/Install.swift

@@ -8,7 +8,27 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Installs previously purchased apps from the Mac App Store.
+	/// Installs one or more apps you have previously acquired from the Mac App Store.
+	///
+	/// This command downloads and installs apps based on their App Store ID.
+	/// You can find app IDs using the `mas search` command or from the App Store URL.
+	///
+	/// By default, if the app is already installed, it will be skipped.
+	/// Use `--force` to reinstall an already installed app.
+	///
+	/// Example:
+	/// ```bash
+	/// mas install 497799835
+	/// ```
+	///
+	/// Output:
+	/// ```
+	/// ==> Downloading Xcode
+	/// ==> Installed Xcode
+	/// ```
+	///
+	/// > Tip:
+	/// > Use `mas list` to check installed apps, and `mas outdated` to find available updates.
 	struct Install: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Install previously purchased apps from the Mac App Store"

Sources/mas/Commands/List.swift

@@ -8,7 +8,42 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Lists all apps installed from the Mac App Store.
+	/// Lists all apps currently installed on your Mac via the Mac App Store.
+	///
+	/// This command displays each app’s:
+	/// - App Store ID
+	/// - Name
+	/// - Installed version
+	///
+	/// The output can be used to:
+	/// - Identify installed apps
+	/// - Verify App Store IDs for use with `mas upgrade`, `mas info`, or `mas uninstall`
+	///
+	/// Example:
+	/// ```bash
+	/// mas list
+	/// ```
+	///
+	/// Output:
+	/// ```
+	/// 497799835 Xcode       (15.4)
+	/// 640199958 Developer   (10.6.5)
+	/// 899247664 TestFlight  (3.5.2)
+	/// ```
+	///
+	/// > Tip:
+	/// > If the output is unexpectedly empty, try resetting the Spotlight index:
+	/// > ```bash
+	/// > sudo mdutil -Eai on
+	/// > ```
+	///
+	/// > Important:
+	/// > This command relies on macOS Spotlight indexing to detect installed apps.
+	/// > If some apps do not appear as expected, you may need to rebuild the metadata index:
+	/// > ```bash
+	/// > sudo mdutil -Eai on
+	/// > ```
+	/// > For details, see the [README Troubleshooting Section](https://github.com/mas-cli/mas#troubleshooting).
 	struct List: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "List all apps installed from the Mac App Store"

Sources/mas/Commands/Lucky.swift

@@ -8,12 +8,32 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Installs the first app returned from searching the Mac App Store (app must
-	/// have been previously purchased).
+	/// Installs the first matching app from the App Store based on a search term.
 	///
-	/// Uses the iTunes Search API:
+	/// This command performs a search using the provided term and attempts to install
+	/// the **first result**, similar to running `mas search` followed by `mas install <first-id>`.
 	///
-	/// https://performance-partners.apple.com/search-api
+	/// It only works for apps that have already been "purchased" using the same Apple ID.
+	///
+	/// Use `--force` to reinstall an app even if it is already installed.
+	///
+	/// Example:
+	/// ```bash
+	/// mas lucky Xcode
+	/// ```
+	///
+	/// Output:
+	/// ```
+	/// ==> Downloading Xcode
+	/// ==> Installed Xcode
+	/// ```
+	///
+	/// > Tip:
+	/// > Use this command when you want a quick, no-fuss install by name.
+	/// > To preview the search results instead, use `mas search <term>`.
+	///
+	/// See also:
+	/// [iTunes Search API](https://performance-partners.apple.com/search-api)
 	struct Lucky: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: """

Sources/mas/Commands/Open.swift

@@ -11,11 +11,30 @@ internal import ArgumentParser
 private var masScheme: String { "macappstore" }
 
 extension MAS {
-	/// Opens app page in 'App Store.app'.
+	/// Opens the specified app’s page in the macOS App Store (`App Store.app`).
 	///
-	/// Uses the iTunes Lookup API:
+	/// This command launches the App Store app using the `macappstore:` URL scheme,
+	/// targeting the app corresponding to the provided App ID.
+	/// If no App ID is specified, the App Store app is simply opened.
 	///
-	/// https://performance-partners.apple.com/search-api
+	/// This is useful when you want to view an app’s description, screenshots, reviews,
+	/// or permissions before deciding to install or update.
+	///
+	/// Example (with App ID):
+	/// ```bash
+	/// mas open 497799835
+	/// ```
+	///
+	/// Example (without App ID):
+	/// ```bash
+	/// mas open
+	/// ```
+	///
+	/// > Tip:
+	/// > Use this command when you want to review an app visually before installation.
+	///
+	/// See also:
+	/// [iTunes Search API](https://performance-partners.apple.com/search-api)
 	struct Open: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Open app page in 'App Store.app'"

Sources/mas/Commands/Outdated.swift

@@ -8,8 +8,40 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Outputs a list of installed apps which have updates available to be
-	/// installed from the Mac App Store.
+	/// Lists apps installed via the Mac App Store that have available updates.
+	///
+	/// This command checks your installed apps against the latest versions available
+	/// on the App Store using the public iTunes Search API.
+	///
+	/// The output shows the App ID, app name, current version, and latest version.
+	///
+	/// Example:
+	/// ```bash
+	/// mas outdated
+	/// ```
+	///
+	/// Output:
+	/// ```
+	/// 497799835 Xcode     (15.4 -> 16.0)
+	/// 640199958 Developer (10.6.5 -> 10.6.6)
+	/// ```
+	///
+	/// > Tip:
+	/// > Use this command before running `mas upgrade` to preview which apps will be updated.
+	///
+	/// > Note:
+	/// > Use `--verbose` to print warnings about apps whose IDs are unknown to the Mac App Store.
+	///
+	/// See also:
+	/// [iTunes Search API](https://performance-partners.apple.com/search-api)
+	///
+	/// > Important:
+	/// > This command relies on macOS Spotlight indexing to detect installed apps.
+	/// > If some apps do not appear as expected, you may need to rebuild the metadata index:
+	/// > ```bash
+	/// > sudo mdutil -Eai on
+	/// > ```
+	/// > For details, see the [README Troubleshooting Section](https://github.com/mas-cli/mas#troubleshooting).
 	struct Outdated: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "List pending app updates from the Mac App Store"

Sources/mas/Commands/Purchase.swift

@@ -8,7 +8,28 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// "Purchases" & installs free apps from the Mac App Store.
+	/// Installs free apps that you haven’t previously acquired from the Mac App Store.
+	///
+	/// This command performs the equivalent of “purchasing” a free app using your Apple ID,
+	/// and installs it on your Mac — similar to how you would claim a free app in the App Store GUI.
+	///
+	/// > Important:
+	/// > This command can only be used with **free apps**.
+	/// > To acquire paid apps, please purchase them directly from the App Store app.
+	///
+	/// > Note:
+	/// > If the app is already installed or previously purchased, it will be skipped.
+	///
+	/// Example:
+	/// ```bash
+	/// mas purchase 497799835
+	/// ```
+	///
+	/// Output:
+	/// ```
+	/// ==> Downloading Xcode
+	/// ==> Installed Xcode
+	/// ```
 	struct Purchase: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "\"Purchase\" & install free apps from the Mac App Store"

Sources/mas/Commands/Region.swift

@@ -8,7 +8,25 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Outputs the region of the Mac App Store.
+	/// Displays the current region setting for the Mac App Store.
+	///
+	/// The output is a two-letter country code (e.g., `US`, `JP`, `FR`)
+	/// indicating the App Store region your system is currently using.
+	///
+	/// This region affects search results, app availability, and pricing.
+	///
+	/// > Note:
+	/// > The region is typically based on your macOS locale or Apple ID configuration.
+	///
+	/// Example:
+	/// ```bash
+	/// mas region
+	/// ```
+	///
+	/// Output:
+	/// ```
+	/// US
+	/// ```
 	struct Region: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Output the region of the Mac App Store"

Sources/mas/Commands/Reset.swift

@@ -9,7 +9,26 @@ internal import ArgumentParser
 private import CommerceKit
 
 extension MAS {
-	/// Kills several macOS processes as a means to reset the app store.
+	/// Attempts to fix certain App Store-related issues by restarting background processes.
+	///
+	/// This command resets the App Store state by force-killing several background services
+	/// used by the App Store and removing the download cache directory.
+	///
+	/// It may help resolve issues where you can’t install or upgrade apps using `mas`,
+	/// or when you receive errors about your Apple account not being authorized.
+	///
+	/// > Tip:
+	/// > Try this command if `mas install` or `mas upgrade` fails unexpectedly.
+	///
+	/// > Note:
+	/// > This command performs actions similar to the App Store's hidden "Reset Application" debug option.
+	///
+	/// Example:
+	/// ```bash
+	/// mas reset
+	/// ```
+	///
+	/// Use `--debug` to print detailed error output when the reset process encounters problems.
 	struct Reset: ParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Reset Mac App Store running processes"