Merge pull request #2 from john-mueller/documentation

Added documentation comments
john-mueller · Feb 14, 2020 · 35621b3 · 35621b3
2 parents 83e9118 + 51963b2
commit 35621b3
Show file tree

Hide file tree

Showing 9 changed files with 40 additions and 52 deletions.
diff --git a/.swiftlint.yml b/.swiftlint.yml
@@ -1,8 +1,6 @@
 disabled_rules:
   - trailing_comma
-  - orphaned_doc_comment
 
 excluded:
   - .build
-  - Tests/TidyHTMLPublishStepTests/Helpers/XCTestManifests.swift
   - Tests/LinuxMain.swift
diff --git a/Package.swift b/Package.swift
@@ -1,10 +1,8 @@
 // swift-tools-version:5.1
 
-/**
- *  TidyHTMLPublishStep
- *  © 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- */
+// TidyHTMLPublishStep
+// © 2020 John Mueller
+// MIT license, see LICENSE.md for details
 
 import PackageDescription
 

diff --git a/Sources/TidyHTMLPublishStep/TidyHTMLPublishStep.swift b/Sources/TidyHTMLPublishStep/TidyHTMLPublishStep.swift
@@ -1,15 +1,19 @@
-/**
- *  TidyHTMLPublishStep
- *  © 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- */
+// TidyHTMLPublishStep
+// © 2020 John Mueller
+// MIT license, see LICENSE.md for details
 
 import Plot
 import Publish
 import SwiftSoup
 
 extension PublishingStep {
-    public static func tidyHTML(indentedBy indent: Indentation.Kind? = nil) -> Self {
+    /// Tidy and indent all generated HTML files.
+    ///
+    /// - Important: This step must be run *after* HTML generation.
+    ///
+    /// - Parameters:
+    ///   - indentation: How each HTML file should be indented. Defaults to one space if not specified.
+    public static func tidyHTML(indentedBy indentation: Indentation.Kind? = nil) -> Self {
         .step(named: "Tidy HTML") { context in
             do {
                 let root = try context.folder(at: "")
@@ -20,7 +24,7 @@ extension PublishingStep {
                     let html = try file.readAsString()
 
                     let outputSettings = OutputSettings()
-                    switch indent {
+                    switch indentation {
                     case let .spaces(num), let .tabs(num):
                         outputSettings.indentAmount(indentAmount: UInt(num))
                     default:
@@ -32,7 +36,7 @@ extension PublishingStep {
 
                     var tidyHTML = try doc.html()
 
-                    if case .tabs = indent {
+                    if case .tabs = indentation {
                         var isPreCode = false
                         tidyHTML = tidyHTML.components(separatedBy: .newlines).map { line in
                             if isPreCode {

diff --git a/Sources/TidyHTMLPublishStep/Website+PostGenerationSteps.swift b/Sources/TidyHTMLPublishStep/Website+PostGenerationSteps.swift
@@ -1,10 +1,8 @@
-/**
- *  TidyHTMLPublishStep
- *  © 2019 John Sundell, 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- *
- *  This file was adapted from the Publish API
- */
+// TidyHTMLPublishStep
+// © 2019 John Sundell, 2020 John Mueller
+// MIT license, see LICENSE.md for details
+//
+// This file was adapted from the Publish API
 
 import Plot
 import Publish

diff --git a/Tests/LinuxMain.swift b/Tests/LinuxMain.swift
@@ -1,8 +1,6 @@
-/**
- *  TidyHTMLPublishStep
- *  © 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- */
+// TidyHTMLPublishStep
+// © 2020 John Mueller
+// MIT license, see LICENSE.md for details
 
 import Foundation
 

diff --git a/Tests/TidyHTMLPublishStepTests/Helpers/HTMLFactoryMock.swift b/Tests/TidyHTMLPublishStepTests/Helpers/HTMLFactoryMock.swift
@@ -1,10 +1,8 @@
-/**
- *  TidyHTMLPublishStep
- *  © 2019 John Sundell, 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- *
- *  This file was copied as-is from the Publish test target
- */
+// TidyHTMLPublishStep
+// © 2019 John Sundell, 2020 John Mueller
+// MIT license, see LICENSE.md for details
+//
+// This file was copied as-is from the Publish test target
 
 import Plot
 import Publish

diff --git a/Tests/TidyHTMLPublishStepTests/Helpers/TidyHTMLTestCase.swift b/Tests/TidyHTMLPublishStepTests/Helpers/TidyHTMLTestCase.swift
@@ -1,10 +1,8 @@
-/**
- *  TidyHTMLPublishStep
- *  © 2019 John Sundell, 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- *
- *  This file was adapted from the Publish test target
- */
+// TidyHTMLPublishStep
+// © 2019 John Sundell, 2020 John Mueller
+// MIT license, see LICENSE.md for details
+//
+// This file was adapted from the Publish test target
 
 import Files
 import Plot

diff --git a/Tests/TidyHTMLPublishStepTests/Helpers/TidyHTMLWebsite.swift b/Tests/TidyHTMLPublishStepTests/Helpers/TidyHTMLWebsite.swift
@@ -1,8 +1,6 @@
-/**
- *  TidyHTMLPublishStep
- *  © 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- */
+// TidyHTMLPublishStep
+// © 2020 John Mueller
+// MIT license, see LICENSE.md for details
 
 import Foundation
 import Plot

diff --git a/Tests/TidyHTMLPublishStepTests/TidyHTMLPublishStepTests.swift b/Tests/TidyHTMLPublishStepTests/TidyHTMLPublishStepTests.swift
@@ -1,8 +1,6 @@
-/**
- *  TidyHTMLPublishStep
- *  © 2020 John Mueller
- *  MIT license, see LICENSE.md for details
- */
+// TidyHTMLPublishStep
+// © 2020 John Mueller
+// MIT license, see LICENSE.md for details
 
 import Plot
 import Publish
@@ -21,7 +19,7 @@ final class TidyHTMLPublishStepTests: TidyHTMLTestCase {
         htmlFactory.makePageHTML = { page, _ in
             HTML(.body(.p(.text(page.title))))
         }
-        
+
         try publishWebsite(
             using: Theme(htmlFactory: htmlFactory),
             content: [