From 52a0638f2bfa25f86082135f2d66e71324834d96 Mon Sep 17 00:00:00 2001 From: Ross Goldberg <484615+rgoldberg@users.noreply.github.com> Date: Sat, 26 Oct 2024 11:43:08 -0400 Subject: [PATCH] Improve help output. Make fish shell completions more consistent with the help output. Resolve #543 Signed-off-by: Ross Goldberg <484615+rgoldberg@users.noreply.github.com> --- Sources/mas/Commands/Account.swift | 2 +- Sources/mas/Commands/Home.swift | 4 +-- Sources/mas/Commands/Info.swift | 2 +- Sources/mas/Commands/Install.swift | 6 ++-- Sources/mas/Commands/List.swift | 2 +- Sources/mas/Commands/Lucky.swift | 10 +++++-- Sources/mas/Commands/Open.swift | 4 +-- Sources/mas/Commands/Outdated.swift | 4 +-- Sources/mas/Commands/Purchase.swift | 4 +-- Sources/mas/Commands/Reset.swift | 4 +-- Sources/mas/Commands/Search.swift | 4 +-- Sources/mas/Commands/SignIn.swift | 4 +-- Sources/mas/Commands/SignOut.swift | 2 +- Sources/mas/Commands/Uninstall.swift | 6 ++-- Sources/mas/Commands/Upgrade.swift | 11 ++++---- Sources/mas/Commands/Vendor.swift | 4 +-- Sources/mas/Commands/Version.swift | 2 +- contrib/completion/mas.fish | 42 +++++++++++++++------------- 18 files changed, 63 insertions(+), 54 deletions(-) diff --git a/Sources/mas/Commands/Account.swift b/Sources/mas/Commands/Account.swift index a9f90a6..328e612 100644 --- a/Sources/mas/Commands/Account.swift +++ b/Sources/mas/Commands/Account.swift @@ -12,7 +12,7 @@ import StoreFoundation extension MAS { struct Account: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Prints the primary account Apple ID" + abstract: "Display the Apple ID signed in in the Mac App Store" ) /// Runs the command. diff --git a/Sources/mas/Commands/Home.swift b/Sources/mas/Commands/Home.swift index c9e186e..8d86a5f 100644 --- a/Sources/mas/Commands/Home.swift +++ b/Sources/mas/Commands/Home.swift @@ -13,10 +13,10 @@ extension MAS { /// https://performance-partners.apple.com/search-api struct Home: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Opens MAS Preview app page in a browser" + abstract: "Open app's Mac App Store web page in the default web browser" ) - @Argument(help: "ID of app to show on MAS Preview") + @Argument(help: "App ID") var appID: AppID /// Runs the command. diff --git a/Sources/mas/Commands/Info.swift b/Sources/mas/Commands/Info.swift index 5352097..5cab3fd 100644 --- a/Sources/mas/Commands/Info.swift +++ b/Sources/mas/Commands/Info.swift @@ -17,7 +17,7 @@ extension MAS { abstract: "Display app information from the Mac App Store" ) - @Argument(help: "ID of app to show info") + @Argument(help: "App ID") var appID: AppID /// Runs the command. diff --git a/Sources/mas/Commands/Install.swift b/Sources/mas/Commands/Install.swift index 9b051e7..7247172 100644 --- a/Sources/mas/Commands/Install.swift +++ b/Sources/mas/Commands/Install.swift @@ -13,12 +13,12 @@ extension MAS { /// Installs previously purchased apps from the Mac App Store. struct Install: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Install from the Mac App Store" + abstract: "Install previously purchased app(s) from the Mac App Store" ) - @Flag(help: "force reinstall") + @Flag(help: "Force reinstall") var force = false - @Argument(help: "app ID(s) to install") + @Argument(help: "App ID(s)") var appIDs: [AppID] /// Runs the command. diff --git a/Sources/mas/Commands/List.swift b/Sources/mas/Commands/List.swift index 94544c9..6817fe5 100644 --- a/Sources/mas/Commands/List.swift +++ b/Sources/mas/Commands/List.swift @@ -12,7 +12,7 @@ extension MAS { /// Command which lists all installed apps. struct List: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Lists apps from the Mac App Store which are currently installed" + abstract: "List apps installed from the Mac App Store for the Apple ID of the current macOS user" ) /// Runs the command. diff --git a/Sources/mas/Commands/Lucky.swift b/Sources/mas/Commands/Lucky.swift index 781f55f..400e5ef 100644 --- a/Sources/mas/Commands/Lucky.swift +++ b/Sources/mas/Commands/Lucky.swift @@ -15,12 +15,16 @@ extension MAS { /// This is handy as many MAS titles can be long with embedded keywords. struct Lucky: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Install the first result from the Mac App Store" + abstract: + """ + Install the first app returned from searching the Mac App Store + (app must have been previously purchased) + """ ) - @Flag(help: "force reinstall") + @Flag(help: "Force reinstall") var force = false - @Argument(help: "the app name to install") + @Argument(help: "Search term") var searchTerm: String /// Runs the command. diff --git a/Sources/mas/Commands/Open.swift b/Sources/mas/Commands/Open.swift index a924895..365715e 100644 --- a/Sources/mas/Commands/Open.swift +++ b/Sources/mas/Commands/Open.swift @@ -16,10 +16,10 @@ extension MAS { /// https://performance-partners.apple.com/search-api struct Open: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Opens app page in 'App Store.app'" + abstract: "Open app page in 'App Store.app'" ) - @Argument(help: "the app ID") + @Argument(help: "App ID") var appID: AppID? /// Runs the command. diff --git a/Sources/mas/Commands/Outdated.swift b/Sources/mas/Commands/Outdated.swift index a495c1b..81b447a 100644 --- a/Sources/mas/Commands/Outdated.swift +++ b/Sources/mas/Commands/Outdated.swift @@ -15,10 +15,10 @@ extension MAS { /// ready to be installed from the Mac App Store. struct Outdated: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Lists pending updates from the Mac App Store" + abstract: "List pending app updates from the Mac App Store for the Apple ID of the current macOS user" ) - @Flag(help: "Show warnings about apps") + @Flag(help: "Display warnings about apps unknown to the Mac App Store") var verbose = false /// Runs the command. diff --git a/Sources/mas/Commands/Purchase.swift b/Sources/mas/Commands/Purchase.swift index d775c64..bdb8a58 100644 --- a/Sources/mas/Commands/Purchase.swift +++ b/Sources/mas/Commands/Purchase.swift @@ -12,10 +12,10 @@ import CommerceKit extension MAS { struct Purchase: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Purchase and download free apps from the Mac App Store" + abstract: "\"Purchase\" and install free apps from the Mac App Store" ) - @Argument(help: "app ID(s) to install") + @Argument(help: "App ID(s)") var appIDs: [AppID] /// Runs the command. diff --git a/Sources/mas/Commands/Reset.swift b/Sources/mas/Commands/Reset.swift index 37ff3e4..055fd2a 100644 --- a/Sources/mas/Commands/Reset.swift +++ b/Sources/mas/Commands/Reset.swift @@ -13,10 +13,10 @@ extension MAS { /// Kills several macOS processes as a means to reset the app store. struct Reset: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Resets the Mac App Store" + abstract: "Reset Mac App Store running processes" ) - @Flag(help: "Enable debug mode") + @Flag(help: "Output debug information") var debug = false /// Runs the command. diff --git a/Sources/mas/Commands/Search.swift b/Sources/mas/Commands/Search.swift index ae36163..9fffa22 100644 --- a/Sources/mas/Commands/Search.swift +++ b/Sources/mas/Commands/Search.swift @@ -17,9 +17,9 @@ extension MAS { abstract: "Search for apps from the Mac App Store" ) - @Flag(help: "Show price of found apps") + @Flag(help: "Display the price of each app") var price = false - @Argument(help: "the app name to search") + @Argument(help: "Search term") var searchTerm: String func run() throws { diff --git a/Sources/mas/Commands/SignIn.swift b/Sources/mas/Commands/SignIn.swift index c94da79..300acdf 100644 --- a/Sources/mas/Commands/SignIn.swift +++ b/Sources/mas/Commands/SignIn.swift @@ -13,10 +13,10 @@ extension MAS { struct SignIn: ParsableCommand { static let configuration = CommandConfiguration( commandName: "signin", - abstract: "Sign in to the Mac App Store" + abstract: "Sign in to an Apple ID in the Mac App Store" ) - @Flag(help: "Complete login with graphical dialog") + @Flag(help: "Provide password via graphical dialog") var dialog = false @Argument(help: "Apple ID") var appleID: String diff --git a/Sources/mas/Commands/SignOut.swift b/Sources/mas/Commands/SignOut.swift index 1c0d49d..6f55e76 100644 --- a/Sources/mas/Commands/SignOut.swift +++ b/Sources/mas/Commands/SignOut.swift @@ -13,7 +13,7 @@ extension MAS { struct SignOut: ParsableCommand { static let configuration = CommandConfiguration( commandName: "signout", - abstract: "Sign out of the Mac App Store" + abstract: "Sign out of the Apple ID currently signed in in the Mac App Store" ) /// Runs the command. diff --git a/Sources/mas/Commands/Uninstall.swift b/Sources/mas/Commands/Uninstall.swift index d9997a7..343d9df 100644 --- a/Sources/mas/Commands/Uninstall.swift +++ b/Sources/mas/Commands/Uninstall.swift @@ -13,13 +13,13 @@ extension MAS { /// Command which uninstalls apps managed by the Mac App Store. struct Uninstall: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Uninstall app installed from the Mac App Store" + abstract: "Uninstall app installed from the Mac App Store for the Apple ID of the current macOS user" ) /// Flag indicating that removal shouldn't be performed. - @Flag(help: "dry run") + @Flag(help: "Perform dry run") var dryRun = false - @Argument(help: "ID of app to uninstall") + @Argument(help: "App ID") var appID: AppID /// Runs the uninstall command. diff --git a/Sources/mas/Commands/Upgrade.swift b/Sources/mas/Commands/Upgrade.swift index 1c1630d..25743f0 100644 --- a/Sources/mas/Commands/Upgrade.swift +++ b/Sources/mas/Commands/Upgrade.swift @@ -14,11 +14,12 @@ extension MAS { /// Command which upgrades apps with new versions available in the Mac App Store. struct Upgrade: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Upgrade outdated apps from the Mac App Store" + abstract: + "Upgrade outdated app(s) installed from the Mac App Store for the Apple ID of the current macOS user" ) - @Argument(help: "app(s) to upgrade") - var appIDs: [String] = [] + @Argument(help: "App ID(s)/app name(s)") + var appIDOrNames: [String] = [] /// Runs the command. func run() throws { @@ -56,9 +57,9 @@ extension MAS { searcher: AppStoreSearcher ) throws -> [(SoftwareProduct, SearchResult)] { let apps = - appIDs.isEmpty + appIDOrNames.isEmpty ? appLibrary.installedApps - : appIDs.flatMap { appID in + : appIDOrNames.flatMap { appID in if let appID = AppID(appID) { // argument is an AppID, lookup apps by id using argument return appLibrary.installedApps(withAppID: appID) diff --git a/Sources/mas/Commands/Vendor.swift b/Sources/mas/Commands/Vendor.swift index 31189e3..d303c94 100644 --- a/Sources/mas/Commands/Vendor.swift +++ b/Sources/mas/Commands/Vendor.swift @@ -13,10 +13,10 @@ extension MAS { /// https://performance-partners.apple.com/search-api struct Vendor: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Opens vendor's app page in a browser" + abstract: "Open vendor's app web page in the default web browser" ) - @Argument(help: "the app ID to show the vendor's website") + @Argument(help: "App ID") var appID: AppID /// Runs the command. diff --git a/Sources/mas/Commands/Version.swift b/Sources/mas/Commands/Version.swift index 4493088..d2f67d7 100644 --- a/Sources/mas/Commands/Version.swift +++ b/Sources/mas/Commands/Version.swift @@ -12,7 +12,7 @@ extension MAS { /// Command which displays the version of the mas tool. struct Version: ParsableCommand { static let configuration = CommandConfiguration( - abstract: "Print version number" + abstract: "Display version number" ) /// Runs the command. diff --git a/contrib/completion/mas.fish b/contrib/completion/mas.fish index de9576f..eccb749 100644 --- a/contrib/completion/mas.fish +++ b/contrib/completion/mas.fish @@ -23,61 +23,65 @@ end complete -c mas -f ### account -complete -c mas -n "__fish_use_subcommand" -f -a account -d "Prints the primary account Apple ID" +complete -c mas -n "__fish_use_subcommand" -f -a account -d "Display the Apple ID signed in in the Mac App Store" complete -c mas -n "__fish_seen_subcommand_from help" -xa "account" ### help complete -c mas -n "__fish_use_subcommand" -f -a help -d "Display general or command-specific help" complete -c mas -n "__fish_seen_subcommand_from help" -xa "help" ### home -complete -c mas -n "__fish_use_subcommand" -f -a home -d "Opens MAS Preview app page in a browser" +complete -c mas -n "__fish_use_subcommand" -f -a home -d "Open app's Mac App Store web page in the default web browser" complete -c mas -n "__fish_seen_subcommand_from help" -xa "home" -complete -c mas -n "__fish_seen_subcommand_from home info install open vendor" -xa "(__fish_mas_list_available)" +complete -c mas -n "__fish_seen_subcommand_from home info install open purchase vendor" -xa "(__fish_mas_list_available)" ### info complete -c mas -n "__fish_use_subcommand" -f -a info -d "Display app information from the Mac App Store" complete -c mas -n "__fish_seen_subcommand_from help" -xa "info" ### install -complete -c mas -n "__fish_use_subcommand" -f -a install -d "Install from the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a install -d "Install previously purchased app(s) from the Mac App Store" complete -c mas -n "__fish_seen_subcommand_from help" -xa "install" complete -c mas -n "__fish_seen_subcommand_from install lucky" -l force -d "Force reinstall" ### list -complete -c mas -n "__fish_use_subcommand" -f -a list -d "Lists apps from the Mac App Store which are currently installed" +complete -c mas -n "__fish_use_subcommand" -f -a list -d "List apps installed from the Mac App Store for the Apple ID of the current macOS user" complete -c mas -n "__fish_seen_subcommand_from help" -xa "list" ### lucky -complete -c mas -n "__fish_use_subcommand" -f -a lucky -d "Install the first result from the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a lucky -d "Install the first app returned from searching the Mac App Store (app must have been previously purchased)" complete -c mas -n "__fish_seen_subcommand_from help" -xa "lucky" ### open -complete -c mas -n "__fish_use_subcommand" -f -a open -d "Opens app page in 'App Store.app'" +complete -c mas -n "__fish_use_subcommand" -f -a open -d "Open app page in 'App Store.app'" complete -c mas -n "__fish_seen_subcommand_from help" -xa "open" ### outdated -complete -c mas -n "__fish_use_subcommand" -f -a outdated -d "Lists pending updates from the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a outdated -d "List pending app updates from the Mac App Store for the Apple ID of the current macOS user" complete -c mas -n "__fish_seen_subcommand_from help" -xa "outdated" +complete -c mas -n "__fish_seen_subcommand_from outdated" -l verbose -d "Display warnings about apps unknown to the Mac App Store" +### purchase +complete -c mas -n "__fish_use_subcommand" -f -a purchase -d "\"Purchase\" and install free apps from the Mac App Store" +complete -c mas -n "__fish_seen_subcommand_from help" -xa "purchase" ### reset -complete -c mas -n "__fish_use_subcommand" -f -a reset -d "Resets the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a reset -d "Reset Mac App Store running processes" complete -c mas -n "__fish_seen_subcommand_from help" -xa "reset" -complete -c mas -n "__fish_seen_subcommand_from reset" -l debug -d "Enable debug mode" +complete -c mas -n "__fish_seen_subcommand_from reset" -l debug -d "Output debug information" ### search complete -c mas -n "__fish_use_subcommand" -f -a search -d "Search for apps from the Mac App Store" complete -c mas -n "__fish_seen_subcommand_from help" -xa "search" -complete -c mas -n "__fish_seen_subcommand_from search" -l price -d "Show price of found apps" +complete -c mas -n "__fish_seen_subcommand_from search" -l price -d "Display the price of each app" ### signin -complete -c mas -n "__fish_use_subcommand" -f -a signin -d "Sign in to the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a signin -d "Sign in to an Apple ID in the Mac App Store" complete -c mas -n "__fish_seen_subcommand_from help" -xa "signin" -complete -c mas -n "__fish_seen_subcommand_from signin" -l dialog -d "Complete login with graphical dialog" +complete -c mas -n "__fish_seen_subcommand_from signin" -l dialog -d "Provide password via graphical dialog" ### signout -complete -c mas -n "__fish_use_subcommand" -f -a signout -d "Sign out of the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a signout -d "Sign out of the Apple ID currently signed in in the Mac App Store" complete -c mas -n "__fish_seen_subcommand_from help" -xa "signout" ### uninstall -complete -c mas -n "__fish_use_subcommand" -f -a uninstall -d "Uninstall app installed from the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a uninstall -d "Uninstall app installed from the Mac App Store for the Apple ID of the current macOS user" complete -c mas -n "__fish_seen_subcommand_from help" -xa "uninstall" -complete -c mas -n "__fish_seen_subcommand_from uninstall" -l dry-run -d "Dry run mode" +complete -c mas -n "__fish_seen_subcommand_from uninstall" -l dry-run -d "Perform dry run" complete -c mas -n "__fish_seen_subcommand_from uninstall" -x -a "(__fish_mas_list_installed)" ### upgrade -complete -c mas -n "__fish_use_subcommand" -f -a upgrade -d "Upgrade outdated apps from the Mac App Store" +complete -c mas -n "__fish_use_subcommand" -f -a upgrade -d "Upgrade outdated app(s) from the Mac App Store for the Apple ID of the current macOS user" complete -c mas -n "__fish_seen_subcommand_from help" -xa "upgrade" complete -c mas -n "__fish_seen_subcommand_from upgrade" -x -a "(__fish_mas_outdated_installed)" ### vendor -complete -c mas -n "__fish_use_subcommand" -f -a vendor -d "Opens vendor's app page in a browser" +complete -c mas -n "__fish_use_subcommand" -f -a vendor -d "Open vendor's app web page in the default web browser" complete -c mas -n "__fish_seen_subcommand_from help" -xa "vendor" ### version -complete -c mas -n "__fish_use_subcommand" -f -a version -d "Print version number" +complete -c mas -n "__fish_use_subcommand" -f -a version -d "Display version number" complete -c mas -n "__fish_seen_subcommand_from help" -xa "version"