Merge pull request #883 from rgoldberg/882

rgoldberg · web-flow · commit 3bc1045d8264 · 2025-05-12T07:14:58.000-04:00
Update `Command` abstracts, DocC &amp; comments
diff --git a/.gitattributes b/.gitattributes
@@ -1,3 +1,3 @@
-# Trailing spaces may be intentional in markdown documents, so these should not
+# Trailing spaces may be intentional in Markdown documents, so these should not
 # be removed.
 **/*.md whitespace=-blank-at-eol
diff --git a/Sources/mas/AppStore/Downloader.swift b/Sources/mas/AppStore/Downloader.swift
@@ -13,7 +13,7 @@ private import CommerceKit
 /// Verifies that each supplied app ID is valid before attempting to download.
 ///
 /// - Parameters:
-///   - appIDs: The app IDs of the apps to be verified and downloaded.
+///   - appIDs: The app IDs of the apps to be verified & downloaded.
 ///   - searcher: The `AppStoreSearcher` used to verify app IDs.
 ///   - purchasing: Flag indicating if the apps will be purchased. Only works for free apps. Defaults to false.
 /// - Throws: If any download fails, immediately throws an error.
diff --git a/Sources/mas/Commands/Account.swift b/Sources/mas/Commands/Account.swift
@@ -9,6 +9,7 @@
 internal import ArgumentParser
 
 extension MAS {
+	/// Displays the Apple Account signed in to the Mac App Store.
 	struct Account: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Display the Apple Account signed in to the Mac App Store"
diff --git a/Sources/mas/Commands/Home.swift b/Sources/mas/Commands/Home.swift
@@ -10,11 +10,14 @@ internal import ArgumentParser
 private import Foundation
 
 extension MAS {
-	/// Opens app page on MAS Preview. Uses the iTunes Lookup API:
+	/// Opens Mac App Store app pages in the default web browser.
+	///
+	/// Uses the iTunes Lookup API:
+	///
 	/// https://performance-partners.apple.com/search-api
 	struct Home: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "Open app's Mac App Store web page in the default web browser"
+			abstract: "Open Mac App Store app pages in the default web browser"
 		)
 
 		@OptionGroup
diff --git a/Sources/mas/Commands/Info.swift b/Sources/mas/Commands/Info.swift
@@ -9,7 +9,10 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Displays app details. Uses the iTunes Lookup API:
+	/// Displays app information from the Mac App Store.
+	///
+	/// Uses the iTunes Lookup API:
+	///
 	/// https://performance-partners.apple.com/search-api
 	struct Info: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
diff --git a/Sources/mas/Commands/Install.swift b/Sources/mas/Commands/Install.swift
@@ -12,7 +12,7 @@ extension MAS {
 	/// Installs previously purchased apps from the Mac App Store.
 	struct Install: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "Install previously purchased app(s) from the Mac App Store"
+			abstract: "Install previously purchased apps from the Mac App Store"
 		)
 
 		@OptionGroup
diff --git a/Sources/mas/Commands/List.swift b/Sources/mas/Commands/List.swift
@@ -9,10 +9,10 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Command which lists all installed apps.
+	/// Lists all apps installed from the Mac App Store.
 	struct List: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "List apps installed from the Mac App Store"
+			abstract: "List all apps installed from the Mac App Store"
 		)
 
 		/// Runs the command.
diff --git a/Sources/mas/Commands/Lucky.swift b/Sources/mas/Commands/Lucky.swift
@@ -9,9 +9,12 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Command which installs the first search result.
+	/// Installs the first app returned from searching the Mac App Store (app must
+	/// have been previously purchased).
 	///
-	/// This is handy as many MAS titles can be long with embedded keywords.
+	/// Uses the iTunes Search API:
+	///
+	/// https://performance-partners.apple.com/search-api
 	struct Lucky: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: """
diff --git a/Sources/mas/Commands/Open.swift b/Sources/mas/Commands/Open.swift
@@ -12,7 +12,10 @@ internal import ArgumentParser
 private var masScheme: String { "macappstore" }
 
 extension MAS {
-	/// Opens app page in MAS app. Uses the iTunes Lookup API:
+	/// Opens app page in 'App Store.app'.
+	///
+	/// Uses the iTunes Lookup API:
+	///
 	/// https://performance-partners.apple.com/search-api
 	struct Open: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
@@ -29,7 +32,7 @@ extension MAS {
 
 		func run(searcher: AppStoreSearcher) async throws {
 			guard let appID else {
-				// If no app ID is given, just open the MAS GUI app
+				// If no app ID was given, just open the MAS GUI app
 				try await openMacAppStore()
 				return
 			}
diff --git a/Sources/mas/Commands/Outdated.swift b/Sources/mas/Commands/Outdated.swift
@@ -9,8 +9,8 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Command which displays a list of installed apps which have available updates
-	/// ready to be installed from the Mac App Store.
+	/// Displays a list of installed apps which have updates available to be
+	/// installed from the Mac App Store.
 	struct Outdated: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "List pending app updates from the Mac App Store"
diff --git a/Sources/mas/Commands/Purchase.swift b/Sources/mas/Commands/Purchase.swift
@@ -9,9 +9,10 @@
 internal import ArgumentParser
 
 extension MAS {
+	/// "Purchases" & installs free apps from the Mac App Store.
 	struct Purchase: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "\"Purchase\" and install free apps from the Mac App Store"
+			abstract: "\"Purchase\" & install free apps from the Mac App Store"
 		)
 
 		@OptionGroup
diff --git a/Sources/mas/Commands/Region.swift b/Sources/mas/Commands/Region.swift
@@ -9,7 +9,7 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Command which interacts with the current region for the Mac App Store.
+	/// Displays the region of the Mac App Store.
 	struct Region: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Display the region of the Mac App Store"
diff --git a/Sources/mas/Commands/Reset.swift b/Sources/mas/Commands/Reset.swift
@@ -29,7 +29,7 @@ extension MAS {
 			// - rm com.apple.appstore download directory
 			// - clear cookies (appears to be a no-op)
 			//
-			// As storeagent no longer exists we will implement a slight variant and kill all
+			// As storeagent no longer exists we will implement a slight variant & kill all
 			// App Store-associated processes
 			// - storeaccountd
 			// - storeassetd
diff --git a/Sources/mas/Commands/Search.swift b/Sources/mas/Commands/Search.swift
@@ -9,18 +9,22 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Search the Mac App Store. Uses the iTunes Search API:
+	/// Searches for apps in the Mac App Store.
+	///
+	/// Uses the iTunes Search API:
+	///
 	/// https://performance-partners.apple.com/search-api
 	struct Search: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "Search for apps from the Mac App Store"
+			abstract: "Search for apps in the Mac App Store"
 		)
 
 		@Flag(help: "Display the price of each app")
 		var price = false
 		@OptionGroup
 		var searchTermOptionGroup: SearchTermOptionGroup
 
+		/// Runs the command.
 		func run() async throws {
 			try await run(searcher: ITunesSearchAppStoreSearcher())
 		}
diff --git a/Sources/mas/Commands/SignIn.swift b/Sources/mas/Commands/SignIn.swift
@@ -9,6 +9,7 @@
 internal import ArgumentParser
 
 extension MAS {
+	/// Signs in to an Apple Account in the Mac App Store.
 	struct SignIn: ParsableCommand {
 		static let configuration = CommandConfiguration(
 			commandName: "signin",
diff --git a/Sources/mas/Commands/SignOut.swift b/Sources/mas/Commands/SignOut.swift
@@ -10,6 +10,7 @@ internal import ArgumentParser
 private import CommerceKit
 
 extension MAS {
+	/// Signs out of the Apple Account currently signed in to the Mac App Store.
 	struct SignOut: ParsableCommand {
 		static let configuration = CommandConfiguration(
 			commandName: "signout",
diff --git a/Sources/mas/Commands/Uninstall.swift b/Sources/mas/Commands/Uninstall.swift
@@ -10,10 +10,10 @@ internal import ArgumentParser
 private import ScriptingBridge
 
 extension MAS {
-	/// Command which uninstalls apps managed by the Mac App Store.
+	/// Uninstalls apps installed from the Mac App Store.
 	struct Uninstall: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "Uninstall app installed from the Mac App Store"
+			abstract: "Uninstall apps installed from the Mac App Store"
 		)
 
 		/// Flag indicating that removal shouldn't be performed.
@@ -22,7 +22,7 @@ extension MAS {
 		@OptionGroup
 		var appIDsOptionGroup: AppIDsOptionGroup
 
-		/// Runs the uninstall command.
+		/// Runs the command.
 		func run() async throws {
 			try run(installedApps: await installedApps)
 		}
diff --git a/Sources/mas/Commands/Upgrade.swift b/Sources/mas/Commands/Upgrade.swift
@@ -9,10 +9,10 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Command which upgrades apps with new versions available in the Mac App Store.
+	/// Upgrades outdated apps installed from the Mac App Store.
 	struct Upgrade: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "Upgrade outdated app(s) installed from the Mac App Store"
+			abstract: "Upgrade outdated apps installed from the Mac App Store"
 		)
 
 		@OptionGroup
@@ -59,15 +59,15 @@ extension MAS {
 			? installedApps
 			: appIDOrNames.flatMap { appIDOrName in
 				if let appID = AppID(appIDOrName) {
-					// Lookup apps by app ID argument
+					// Find installed apps by app ID argument
 					let installedApps = installedApps.filter { $0.id == appID }
 					if installedApps.isEmpty {
 						printError(appID.unknownMessage)
 					}
 					return installedApps
 				}
 
-				// Lookup apps by name argument
+				// Find installed apps by name argument
 				let installedApps = installedApps.filter { $0.name == appIDOrName }
 				if installedApps.isEmpty {
 					printError("Unknown app name '", appIDOrName, "'", separator: "")
diff --git a/Sources/mas/Commands/Vendor.swift b/Sources/mas/Commands/Vendor.swift
@@ -10,11 +10,14 @@ internal import ArgumentParser
 private import Foundation
 
 extension MAS {
-	/// Opens vendor's app page in a browser. Uses the iTunes Lookup API:
+	/// Opens apps' vendor pages in the default web browser.
+	///
+	/// Uses the iTunes Lookup API:
+	///
 	/// https://performance-partners.apple.com/search-api
 	struct Vendor: AsyncParsableCommand {
 		static let configuration = CommandConfiguration(
-			abstract: "Open vendor's app web page in the default web browser"
+			abstract: "Open apps' vendor pages in the default web browser"
 		)
 
 		@OptionGroup
diff --git a/Sources/mas/Commands/Version.swift b/Sources/mas/Commands/Version.swift
@@ -9,7 +9,7 @@
 internal import ArgumentParser
 
 extension MAS {
-	/// Command which displays the version of the mas tool.
+	/// Displays the version of the mas tool.
 	struct Version: ParsableCommand {
 		static let configuration = CommandConfiguration(
 			abstract: "Display version number"
diff --git a/Sources/mas/Controllers/ITunesSearchAppStoreSearcher.swift b/Sources/mas/Controllers/ITunesSearchAppStoreSearcher.swift
@@ -8,7 +8,10 @@
 
 private import Foundation
 
-/// Manages searching the MAS catalog. Uses the iTunes Search and Lookup APIs:
+/// Manages searching the MAS catalog.
+///
+/// Uses the iTunes Search & Lookup APIs:
+///
 /// https://performance-partners.apple.com/search-api
 struct ITunesSearchAppStoreSearcher: AppStoreSearcher {
 	enum Entity: String {
@@ -50,7 +53,7 @@ struct ITunesSearchAppStoreSearcher: AppStoreSearcher {
 	/// - Throws: An `Error` if any problem occurs.
 	func search(for searchTerm: String, inRegion region: ISORegion?) async throws -> [SearchResult] {
 		// Search for apps for compatible platforms, in order of preference.
-		// Macs with Apple Silicon can run iPad and iPhone apps.
+		// Macs with Apple Silicon can run iPad & iPhone apps.
 		#if arch(arm64)
 		let entities = [Entity.desktopSoftware, .iPadSoftware, .iPhoneSoftware]
 		#else
@@ -87,7 +90,7 @@ struct ITunesSearchAppStoreSearcher: AppStoreSearcher {
 	///
 	/// - Parameters:
 	///   - searchTerm: term for which to search in MAS.
-	///   - region: The `ISORegion` of the storefront in which to lookup apps.
+	///   - region: The `ISORegion` of the storefront in which to search for apps.
 	///   - entity: OS platform of apps for which to search.
 	/// - Returns: URL for the search service.
 	/// - Throws: An `MASError.urlParsing` if `searchTerm` can't be encoded.
diff --git a/Sources/mas/Formatters/Printing.swift b/Sources/mas/Formatters/Printing.swift
@@ -25,24 +25,24 @@ func print(_ message: String, to fileHandle: FileHandle) {
 	}
 }
 
-/// Prints to stdout.
+/// Prints to `stdout`.
 func printInfo(_ items: Any..., separator: String = " ", terminator: String = "\n") {
 	print(items, separator: separator, terminator: terminator)
 }
 
-/// Clears current line from stdout, then prints to stdout, then flushes stdout.
+/// Clears current line from `stdout`, then prints to `stdout`, then flushes `stdout`.
 func printEphemeral(_ items: Any..., separator: String = " ", terminator: String = "\n") {
 	clearCurrentLine(fromStream: stdout)
 	print(items, separator: separator, terminator: terminator)
 	fflush(stdout)
 }
 
-/// Clears current line from stdout.
+/// Clears current line from `stdout`.
 func terminateEphemeralPrinting() {
 	clearCurrentLine(fromStream: stdout)
 }
 
-/// Prints to stdout prefixed with a blue arrow.
+/// Prints to `stdout`; if connected to a terminal, prefixes a blue arrow.
 func printNotice(_ items: Any..., separator: String = " ", terminator: String = "\n") {
 	if isatty(fileno(stdout)) != 0 {
 		// Blue bold arrow, Bold text
@@ -55,7 +55,7 @@ func printNotice(_ items: Any..., separator: String = " ", terminator: String =
 	}
 }
 
-/// Prints to stderr prefixed with "Warning:" underlined in yellow.
+/// Prints to `stderr`; if connected to a terminal, prefixes "Warning:" underlined in yellow.
 func printWarning(_ items: Any..., separator: String = " ", terminator: String = "\n") {
 	if isatty(fileno(stderr)) != 0 {
 		// Yellow, underlined "Warning:" prefix
@@ -68,7 +68,7 @@ func printWarning(_ items: Any..., separator: String = " ", terminator: String =
 	}
 }
 
-/// Prints to stderr prefixed with "Error:" underlined in red.
+/// Prints to `stderr`; if connected to a terminal, prefixes "Error:" underlined in red.
 func printError(_ items: Any..., separator: String = " ", terminator: String = "\n") {
 	if isatty(fileno(stderr)) != 0 {
 		// Red, underlined "Error:" prefix
diff --git a/contrib/completion/mas.fish b/contrib/completion/mas.fish
diff --git a/docs/sample.swift b/docs/sample.swift
diff --git a/script/format b/script/format
diff --git a/script/lint b/script/lint

Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ extension MAS {`
`12`	`12`	`/// Installs previously purchased apps from the Mac App Store.`
`13`	`13`	`struct Install: AsyncParsableCommand {`
`14`	`14`	`static let configuration = CommandConfiguration(`
`15`		`- abstract: "Install previously purchased app(s) from the Mac App Store"`
	`15`	`+ abstract: "Install previously purchased apps from the Mac App Store"`
`16`	`16`	`)`
`17`	`17`
`18`	`18`	`@OptionGroup`