Improve Swift comments & sample.swift

Sources/mas/AppStore/PurchaseDownloadObserver.swift

@@ -24,7 +24,7 @@ class PurchaseDownloadObserver: CKDownloadQueueObserver {
 	}
 
 	deinit {
-		// do nothing
+		// Do nothing
 	}
 
 	func downloadQueue(_ queue: CKDownloadQueue, statusChangedFor download: SSDownload) {
@@ -65,7 +65,7 @@ class PurchaseDownloadObserver: CKDownloadQueueObserver {
 	}
 
 	func downloadQueue(_: CKDownloadQueue, changedWithAddition _: SSDownload) {
-		// do nothing
+		// Do nothing
 	}
 
 	func downloadQueue(_: CKDownloadQueue, changedWithRemoval download: SSDownload) {

Sources/mas/Commands/Upgrade.swift

@@ -65,15 +65,15 @@ extension MAS {
 				? installedApps
 				: appIDOrNames.flatMap { appIDOrName in
 					if let appID = AppID(appIDOrName) {
-						// argument is an AppID, lookup apps by id using argument
+						// Argument is an AppID, lookup apps by id using argument
 						let installedApps = installedApps.filter { $0.id == appID }
 						if installedApps.isEmpty {
 							printError(appID.unknownMessage)
 						}
 						return installedApps
 					}
 
-					// argument is not an AppID, lookup apps by name using argument
+					// Argument is not an AppID, lookup apps by name using argument
 					let installedApps = installedApps.filter { $0.name == appIDOrName }
 					if installedApps.isEmpty {
 						printError("Unknown app name '", appIDOrName, "'", separator: "")

Sources/mas/Formatters/AppListFormatter.swift

@@ -15,7 +15,7 @@ enum AppListFormatter {
 	/// - Parameter installedApps: List of installed apps.
 	/// - Returns: Multiline text output.
 	static func format(_ installedApps: [InstalledApp]) -> String {
-		// longest app name for right space padding
+		// Longest app name for right space padding
 		guard let maxAppNameLength = installedApps.map(\.name.count).max() else {
 			return ""
 		}

Sources/mas/Formatters/SearchResultFormatter.swift

@@ -15,7 +15,7 @@ enum SearchResultFormatter {
 	///   - includePrice: Indicates whether to include prices in the output
 	/// - Returns: Multiline text output.
 	static func format(_ results: [SearchResult], includePrice: Bool = false) -> String {
-		// longest app name for right space padding
+		// Longest app name for right space padding
 		guard let maxAppNameLength = results.map(\.trackName.count).max() else {
 			return ""
 		}

Tests/masTests/Formatters/AppListFormatterSpec.swift

@@ -13,7 +13,7 @@ import Quick
 
 final class AppListFormatterSpec: QuickSpec {
 	override static func spec() {
-		// static func reference
+		// Static func reference
 		let format = AppListFormatter.format(_:)
 
 		describe("app list formatter") {

Tests/masTests/Formatters/SearchResultFormatterSpec.swift

@@ -13,7 +13,7 @@ import Quick
 
 final class SearchResultFormatterSpec: QuickSpec {
 	override static func spec() {
-		// static func reference
+		// Static func reference
 		let format = SearchResultFormatter.format(_:includePrice:)
 
 		describe("search results formatter") {

docs/sample.swift

@@ -1,51 +1,50 @@
-// Don't include generated header comments
+// Don't include generated header comments.
 
 // MARK: Types and naming
 
 /// Types begin with a capital letter.
 struct User {
 	let name: String
 
-	/// if the first letter of an acronym is lowercase, the entire thing should
+	/// If the first letter of an acronym is lowercase, the entire thing should
 	/// be lowercase.
 	let json: Any
 
-	/// if the first letter of an acronym is uppercase, the entire thing should
+	/// If the first letter of an acronym is uppercase, the entire thing should
 	/// be uppercase.
 	static func decode(from json: JSON) -> Self {
 		Self(json: json)
 	}
 }
 
-/// Use () for void arguments and Void for void return types.
+/// Use `()` for void arguments and `Void` for void return types.
 let closure: () -> Void = {
 	// Do nothing
 }
 
-/// When using classes, default to marking them as final.
+/// When using classes, default to marking them as `final`.
 final class MyClass {
 	// Empty class
 }
 
-/// Use typealias when closures are referenced in multiple places.
+/// Use `typealias` when closures are referenced in multiple places.
 typealias CoolClosure = (Int) -> Bool
 
 /// Use aliased parameter names when function parameters are ambiguous.
 func yTown(some: Int, withCallback callback: CoolClosure) -> Bool {
 	callback(some)
 }
 
-/// It's OK to use $ variable references if the closure is very short and
-/// readability is maintained.
+/// Use `$` variable references if the closure fits on one line.
 let cool = yTown(5) { $0 == 6 }
 
-/// Use full variable names when closures are more complex.
+/// Use explicit variable names if the closure is on multiple lines.
 let cool = yTown(5) { foo in
 	max(foo, 0)
 	// …
 }
 
-// Strongify weak references in async closures
+// Strongify weak references in async closures.
 APIClient.getAwesomeness { [weak self] result in
 	guard let self else {
 		return
@@ -61,7 +60,7 @@ func someUnauditedAPI(thing: String?) {
 	}
 }
 
-/// When the type is known you can let the compiler infer.
+/// When the type is known, let the compiler infer.
 let response: Response = .success(NSData())
 
 func doSomeWork() -> Response {
@@ -87,25 +86,11 @@ private extension MyClass {
 
 // MARK: Breaking up long lines
 
-// One expression to evaluate and short or no return
-guard let singleTest = somethingFailable() else {
-	return
-}
-
-guard statementThatShouldBeTrue else {
-	return
-}
-
-// If a guard clause requires multiple lines, chop down, then start `else` new line
-// In this case, always chop down else clause.
+// If a guard clause requires multiple lines, chop it down, then start the else
+// clause on a new line.
 guard
 	let oneItem = somethingFailable(),
 	let secondItem = somethingFailable2()
 else {
 	return
 }
-
-// If the return in else is long, move to next line
-guard let something = somethingFailable() else {
-	return someFunctionThatDoesSomethingInManyWordsOrLines()
-}