Update comment style

Improve documentation

Sources/Backend/ImageProcessing/Image.swift

@@ -63,8 +63,8 @@ struct Image {
                 throw ImageProcessingError.pdfDocumentError
             }
             let mediaBox = page.getBoxRect(.mediaBox)
-            // 1024x1024 is the size of the largest image we need to produce.
-            // Scale down if more than 4 times larger.
+            // 1024x1024 is the size of the largest image we need to produce;
+            // scale down if more than 4 times larger
             let scaleFactor = Self.getScaleFactor(forSize: mediaBox.size, minDimension: 0, maxDimension: 1024 * 4)
             let destRect = mediaBox.applying(CGAffineTransform(scaleX: scaleFactor, y: scaleFactor))
             let context = try Self.makeGraphicsContext(size: destRect.size)
@@ -77,16 +77,16 @@ struct Image {
             self.init(cgImage: cgImage)
         case .svg:
             // HACK: SwiftDraw logs some implementation details to stderr when it finds
-            // something in an SVG file it doesn't like. Temporarily redirect stderr to
-            // an empty file and throw our own error on failure.
+            // something in an SVG file it doesn't like; temporarily redirect stderr to
+            // an empty file and throw our own error on failure
             let svg = try OutputHandle.standardError.redirect {
                 guard let svg = SVG(fileURL: url) else {
                     throw ImageProcessingError.svgCreationError
                 }
                 return svg
             }
-            // 1024x1024 is the size of the largest image we need to produce.
-            // Scale up if smaller. Scale down if more than 4 times larger.
+            // 1024x1024 is the size of the largest image we need to produce;
+            // scale up if smaller; scale down if more than 4 times larger
             let scaleFactor = Self.getScaleFactor(forSize: svg.size, minDimension: 1024, maxDimension: 1024 * 4)
             let data = try svg.pngData(size: svg.size, scale: scaleFactor)
             let options = Self.getImageSourceOptions(type: .png)
@@ -172,8 +172,8 @@ struct Image {
     func resized(to size: CGSize) throws -> Self {
         let context = try Self.makeGraphicsContext(size: size)
 
-        // Create a new size from the values in the context to be sure we don't
-        // cut off the edges of the new image.
+        // create a new size from the values in the context to be sure we don't
+        // cut off the edges of the new image
         let sizeIntegral = CGSize(width: context.width, height: context.height)
 
         let rect = CGRect(origin: .zero, size: sizeIntegral)

Sources/Backend/Runners/ListFormats.swift

@@ -14,10 +14,10 @@ struct ListFormats: Runner {
         let (paddedColumns, maxCellCount) = columns.reduce(
             into: (paddedColumns: [PaddedColumn](), maxCellCount: 0)
         ) { outerState, column in
-            // Get the max length of the column.
+            // get the max length of the column
             let length = column.map { $0.count }.max() ?? 0
 
-            // Produce an array of padded cells, keeping track of the total cell count.
+            // produce an array of padded cells, keeping track of the total cell count
             let (cells, cellCount) = column.reduce(
                 into: (cells: [String](), cellCount: 0)
             ) { innerState, cell in
@@ -26,18 +26,18 @@ struct ListFormats: Runner {
                 innerState.cellCount += 1
             }
 
-            // Append a new padded column value consisting of the padded cells, max
-            // length, and cell count.
+            // append a new padded column value consisting of the padded cells, max
+            // length, and cell count
             outerState.paddedColumns.append((cells, length, cellCount))
 
             if cellCount > outerState.maxCellCount {
-                // We have a new max cell count. Update it.
+                // we have a new max cell count; update it
                 outerState.maxCellCount = cellCount
             }
         }
 
         let headerLines: [String] = {
-            // Divide the header and body with a dashed line.
+            // divide the header and body with a dashed line
             let divider: String = {
                 let dash = "-"
                 return paddedColumns.map { column in
@@ -51,19 +51,19 @@ struct ListFormats: Runner {
         let lines = headerLines + (0..<maxCellCount).map { cellIndex in
             paddedColumns.map { column in
                 guard cellIndex < column.cellCount else {
-                    // We're past the end of this column. Pad with whitespace to the start
+                    // we're past the end of this column; pad with whitespace to the start
                     // of the next column (note that there might not actually _be_ a next
                     // column, but it's easier to just trim the result once we're finished
-                    // instead of checking the column index on every iteration).
+                    // instead of checking the column index on every iteration)
                     return String(repeating: pad, count: column.length)
                 }
                 return column.cells[cellIndex]
             }
             .joined(separator: pad)
-            .trimmingSuffix { $0.isWhitespace } // Lazy hack (see above)
+            .trimmingSuffix { $0.isWhitespace } // lazy hack (see above)
         }
 
-        // Finally, join the lines into a single string.
+        // finally, join the lines into a single string.
         return lines.joined(separator: "\n")
     }
 

Sources/Backend/Utilities/OutputHandle.swift

@@ -76,13 +76,13 @@ public struct OutputHandle {
 
         let handle = handle ?? Self()
 
-        // Create a temporary file descriptor to maintain a reference to the original
-        // file, then point this handle's descriptor at the replacement handle's file.
+        // create a temporary file descriptor to maintain a reference to the original
+        // file, then point this handle's descriptor at the replacement handle's file
         let tempfd = dup(fileDescriptor)
         dup2(handle.fileDescriptor, fileDescriptor)
 
         defer {
-            // Point this handle back to the original file and close the temp.
+            // point this handle back to the original file and close the temp
             dup2(tempfd, fileDescriptor)
             close(tempfd)
         }
@@ -109,7 +109,7 @@ extension OutputHandle: Hashable {
 extension OutputHandle: TextOutputStream {
     private func write<S: Sequence>(_ elements: S, to fileHandle: FileHandle) where S.Element == UInt8 {
         if #available(macOS 10.15.4, *) {
-            // We want to be alerted of a failure here, so a force try is acceptable.
+            // we want to know about a failure here, so a force try is acceptable
             // swiftlint:disable:next force_try
             try! fileHandle.write(contentsOf: Data(elements))
         } else {

Sources/Backend/Utilities/OutputType.swift

@@ -3,8 +3,12 @@
 //  createicns
 //
 
+/// The output type of the `createicns` command.
 public enum OutputType: String, CaseIterable {
+    /// An `icns` icon file.
     case icns
+    /// An `iconset` folder.
     case iconset
+    /// Infer the type from the output path extension.
     case infer
 }

Sources/Frontend/Options.swift

@@ -29,7 +29,7 @@ struct Options: ParsableArguments {
 
     mutating func validate() throws {
         if isIconset {
-            type = .iconset // Set the type to simulate the behavior of --iconset
+            type = .iconset // set the type to simulate the behavior of "--iconset"
             print(
                 FormattedText("warning:", color: .yellow, style: .bold)
                     .appending(" '")