Doc coverage 100%

Author: ikhvorost

Sources/SwiftSource/SwiftAccessLevel.swift

@@ -23,12 +23,17 @@
 
 import SwiftSyntax
 
-
+/// Swift declaration access level.
 public enum SwiftAccessLevel: Int, Codable {
+  /// Classes and methods marked as open can be subclassed and overridden respectively out of their defining module.
   case `open`
+  /// Accessible from everywhere.
   case `public`
+  /// Accessible only within the defined module (default)
   case `internal`
+  /// Accessible only within the current swift file.
   case `fileprivate`
+  /// Accessible only within the defined class or struct.
   case `private`
 
  init(modifiers: DeclModifierListSyntax) {

Sources/SwiftSource/SwiftComment.swift

@@ -23,25 +23,41 @@
 
 import SwiftSyntax
 
-
+/// Swift declaration comment.
 public struct SwiftComment: Codable {
+  /// Text of this comment.
   public let text: String
+  /// Returns `true` if this comment is documentation (starting with '///' or '/**').
   public var isDoc: Bool
 
   init?(piece: TriviaPiece) {
     switch piece {
       case .lineComment(let value):
         text = value
+          .replacingOccurrences(of: "//", with: "")
+          .trimmingCharacters(in: .whitespaces)
         isDoc = false
+        
       case .blockComment(let value):
         text = value
+          .replacingOccurrences(of: "/*", with: "")
+          .replacingOccurrences(of: "*/", with: "")
+          .trimmingCharacters(in: .whitespaces)
         isDoc = false
+        
       case .docLineComment(let value):
         text = value
-        isDoc = true
+          .replacingOccurrences(of: "///", with: "")
+          .trimmingCharacters(in: .whitespaces)
+        isDoc = !text.isEmpty
+        
       case .docBlockComment(let value):
         text = value
-        isDoc = true
+          .replacingOccurrences(of: "/**", with: "")
+          .replacingOccurrences(of: "*/", with: "")
+          .trimmingCharacters(in: .whitespaces)
+        isDoc = !text.isEmpty
+        
       default:
         return nil
     }

Sources/SwiftSource/SwiftDeclaration.swift

@@ -47,15 +47,23 @@ fileprivate struct StringBuilder {
   }
 }
 
+/// Swift declaration.
 public struct SwiftDeclaration: Codable {
+  /// List of comments of this declaration.
   public let comments: [SwiftComment]
+  /// Access level of this declaration.
   public let accessLevel: SwiftAccessLevel
+  /// The keyword for this declaration.
   public var keyword: SwiftKeyword
+  /// The name of this declaration.
   public let name: String
+  /// The line in the file where this declaration resides.
   public let line: Int
+  /// The offset from the beginning of the line where this declaration resides.
   public let column: Int
 
-  public var isDocumented: Bool {
+  /// Whether or not this declaration has documentation.
+  public var hasDoc: Bool {
     comments.first { $0.isDoc } != nil
   }
 

Sources/SwiftSource/SwiftKeyword.swift

@@ -23,24 +23,41 @@
 
 import SwiftSyntax
 
-
+/// Swift declaration keyword.
 public enum SwiftKeyword: String, Codable {
+  /// `actor`
   case actor
+  /// `associatedtype`
   case `associatedtype`
+  /// Enum `case`
   case `case`
+  /// `class`
   case `class`
+  /// `enum`
   case `enum`
+  /// `extension`
   case `extension`
+  /// `func`
   case `func`
-  //case `import`
+  // case `import`
+  /// `init`
   case `init`
+  /// Const variable `let`
   case `let`
+  /// `macro`
   case macro
+  /// `operator`
   case `operator`
+  /// `precedencegroup`
   case `precedencegroup`
+  /// `protocol`
   case `protocol`
+  /// `struct`
   case `struct`
+  /// `subscript`
   case `subscript`
+  /// `typealias`
   case `typealias`
+  /// Variable `var`
   case `var`
 }

Sources/SwiftSource/SwiftSource.swift

@@ -25,26 +25,32 @@ import Foundation
 import SwiftSyntax
 
 
+/// Swift source
 public struct SwiftSource: Codable {
+  /// Source URL
   public let url: URL?
+  /// List of all parsed declarations
   public let declarations: [SwiftDeclaration]
 
   private init(url: URL?, source: String) {
     self.url = url
     let visitor = Visitor(source: source)
     self.declarations = visitor.declarations
   }
-    
+  
+  /// Create from a specified swift code.
   public init(source: String) {
     self.init(url: nil, source: source)
   }
 
-  public init(fileURL: URL) throws {
-    let source = try String(contentsOf: fileURL)
-    self.init(url: fileURL, source: source)
+  /// Create from a specified URL.
+  public init(url: URL) throws {
+    let source = try String(contentsOf: url)
+    self.init(url: url, source: source)
   }
 
-  public func declarations(level: SwiftAccessLevel) -> [SwiftDeclaration] {
-    declarations.filter { $0.accessLevel.rawValue <= level.rawValue }
+  /// List of declarations with a specified access level
+  public func declarations(accessLevel: SwiftAccessLevel) -> [SwiftDeclaration] {
+    declarations.filter { $0.accessLevel.rawValue <= accessLevel.rawValue }
   }
 }

Sources/swift-doc-coverage/main.swift

@@ -122,10 +122,10 @@ struct SwiftDocCoverage: ParsableCommand {
     sources = try urls.map { url in
       let sourceTime = Date()
 
-      let source = try SwiftSource(fileURL: url)
+      let source = try SwiftSource(url: url)
 
       if report != .json {
-        let declarations = source.declarations(level: minimumAccessLevel.accessLevel)
+        let declarations = source.declarations(accessLevel: minimumAccessLevel.accessLevel)
         if declarations.count > 0 {
           index += 1
           let filePath = url.absoluteString
@@ -142,12 +142,12 @@ struct SwiftDocCoverage: ParsableCommand {
     }
 
     if report == .coverage {
-      let declarations = sources.flatMap { $0.declarations(level: minimumAccessLevel.accessLevel) }
+      let declarations = sources.flatMap { $0.declarations(accessLevel: minimumAccessLevel.accessLevel) }
       guard declarations.count > 0 else {
         throw Errors.declarationsNotFound
       }
 
-      let undocumented = declarations.filter { $0.isDocumented == false }
+      let undocumented = declarations.filter { $0.hasDoc == false }
 
       let totalCount = declarations.count
       let documentedCount = totalCount - undocumented.count
@@ -246,7 +246,7 @@ struct SwiftDocCoverage: ParsableCommand {
   static func coverage(index: Int, time: Date, filePath: String, declarations: [SwiftDeclaration], out: Output?) {
     assert(declarations.count > 0)
 
-    let undocumented = declarations.filter { $0.isDocumented == false }
+    let undocumented = declarations.filter { $0.hasDoc == false }
 
     let totalCount = declarations.count
     let documentedCount = totalCount - undocumented.count
@@ -269,7 +269,7 @@ struct SwiftDocCoverage: ParsableCommand {
     assert(declarations.count > 0)
 
     declarations
-      .filter { $0.isDocumented == false }
+      .filter { $0.hasDoc == false }
       .forEach {
         out?.write("\(filePath):\($0.line):\($0.column): warning: No documentation for '\($0.name)'.")
       }

Tests/SwiftDocCoverageTests/SwiftDocCoverageTests.swift

@@ -421,30 +421,45 @@ final class SourceCodeTests: XCTestCase {
     /// A documentation line comment
     /** A documentation 
     block comment */
-    
+    ///
+    /**     */
     mutating public func eat(_ food: Food, quantity: Int) throws -> Int { return 0 }
     """
     let source = SwiftSource(source: code)
     XCTAssert(source.declarations.count == 1)
-    XCTAssert(source.declarations[0].comments.count == 4)
-    XCTAssert(source.declarations[0].comments[0].text == "// A developer line comment")
-    XCTAssert(source.declarations[0].comments[1].text == "/* A developer block comment */")
-    XCTAssert(source.declarations[0].comments[2].text == "/// A documentation line comment")
-    XCTAssert(source.declarations[0].comments[3].text == "/** A documentation \nblock comment */")
+    XCTAssert(source.declarations[0].comments.count == 6)
+    
+    XCTAssert(source.declarations[0].comments[0].text == "A developer line comment")
+    XCTAssert(source.declarations[0].comments[0].isDoc == false)
+    
+    XCTAssert(source.declarations[0].comments[1].text == "A developer block comment")
+    XCTAssert(source.declarations[0].comments[1].isDoc == false)
+    
+    XCTAssert(source.declarations[0].comments[2].text == "A documentation line comment")
+    XCTAssert(source.declarations[0].comments[2].isDoc == true)
+    
+    XCTAssert(source.declarations[0].comments[3].text == "A documentation \nblock comment")
+    XCTAssert(source.declarations[0].comments[3].isDoc == true)
+    
+    XCTAssert(source.declarations[0].comments[4].text == "")
+    XCTAssert(source.declarations[0].comments[4].isDoc == false)
+    
+    XCTAssert(source.declarations[0].comments[5].text == "")
+    XCTAssert(source.declarations[0].comments[5].isDoc == false)
   }
 }
 
 final class SourceFileTests: XCTestCase {
 
   func test_no_file() {
     let fileURL = resourcesUrl.appendingPathComponent("File.swift")
-    XCTAssertThrowsError(try SwiftSource(fileURL: fileURL)) { error in
+    XCTAssertThrowsError(try SwiftSource(url: fileURL)) { error in
       XCTAssert(error.localizedDescription == "The file “File.swift” couldn’t be opened because there is no such file.")
     }
   }
 
   func test_file() throws {
-    let source = try SwiftSource(fileURL: rectUrl)
+    let source = try SwiftSource(url: rectUrl)
     XCTAssert(source.declarations.count == 5)
   }
 }
@@ -488,23 +503,23 @@ final class SwiftDocCoverageTests: XCTestCase {
     var cmd = try SwiftDocCoverage.run(rectUrl.path, "--minimum-access-level", "open")
     XCTAssert(cmd.sources.count == 1)
     XCTAssert(cmd.sources[0].declarations.count == 5)
-    XCTAssert(cmd.sources[0].declarations(level: .open).count == 1)
+    XCTAssert(cmd.sources[0].declarations(accessLevel: .open).count == 1)
 
     cmd = try SwiftDocCoverage.run(rectUrl.path, "--minimum-access-level", "public")
     XCTAssert(cmd.sources.count == 1)
-    XCTAssert(cmd.sources[0].declarations(level: .public).count == 2)
+    XCTAssert(cmd.sources[0].declarations(accessLevel: .public).count == 2)
 
     cmd = try SwiftDocCoverage.run(rectUrl.path, "--minimum-access-level", "internal")
     XCTAssert(cmd.sources.count == 1)
-    XCTAssert(cmd.sources[0].declarations(level: .internal).count == 3)
+    XCTAssert(cmd.sources[0].declarations(accessLevel: .internal).count == 3)
 
     cmd = try SwiftDocCoverage.run(rectUrl.path, "--minimum-access-level", "fileprivate")
     XCTAssert(cmd.sources.count == 1)
-    XCTAssert(cmd.sources[0].declarations(level: .fileprivate).count == 4)
+    XCTAssert(cmd.sources[0].declarations(accessLevel: .fileprivate).count == 4)
 
     cmd = try SwiftDocCoverage.run(rectUrl.path, "--minimum-access-level", "private")
     XCTAssert(cmd.sources.count == 1)
-    XCTAssert(cmd.sources[0].declarations(level: .private).count == 5)
+    XCTAssert(cmd.sources[0].declarations(accessLevel: .private).count == 5)
   }
 
   func test_ignore_filename_regex() throws {