Option to skip elements with no comments (SourceDocs#76)

Author: Fiser33

README.md

@@ -132,7 +132,8 @@ Typing `sourcedocs help <command>` we get a list of all options for that command
       -m, --module-name-path  Include the module name as part of the output folder path 
       -c, --clean             Delete output folder before generating documentation 
       -l, --collapsible       Put methods, properties and enum cases inside collapsible blocks 
-      -t, --table-of-contents Generate a table of contents with properties and methods for each type 
+      -t, --table-of-contents Generate a table of contents with properties and methods for each type
+      -s, --skip-empty        Do not generate documentation for files with no comments. 
       -r, --reproducible-docs Generate documentation that is reproducible: only depends on the sources.
                               For example, this will avoid adding timestamps on the generated files. 
       -h, --help              Show help information

Sources/SourceDocsCLI/GenerateCommand.swift

@@ -55,6 +55,10 @@ extension SourceDocs {
               help: "Generate a table of contents with properties and methods for each type")
         var tableOfContents = false
 
+        @Flag(name: .shortAndLong,
+              help: "Do not generate documentation for files with no comments.")
+        var skipEmpty = false
+
         @Argument(help: "List of arguments to pass to xcodebuild")
         var xcodeArguments: [String] = []
 
@@ -74,7 +78,7 @@ extension SourceDocs {
                                           minimumAccessLevel: minACL, includeModuleNameInPath: moduleNamePath,
                                           clean: clean, collapsibleBlocks: collapsible,
                                           tableOfContents: tableOfContents, xcodeArguments: xcodeArguments,
-                                          reproducibleDocs: reproducibleDocs)
+                                          reproducibleDocs: reproducibleDocs, skipEmpty: skipEmpty)
 
             try DocumentationGenerator(options: options).run()
         }

Sources/SourceDocsLib/DocumentationGenerator/DocumentationGenerator.swift

@@ -26,6 +26,7 @@ import SourceKittenFramework
 ///   - xcodeArguments: Array of `String` arguments to pass to xcodebuild. Defaults to an empty array.
 ///   - reproducibleDocs: generate documentation that is reproducible: only depends on the sources.
 ///     For example, this will avoid adding timestamps on the generated files. Defaults to false.
+///   - skipEmpty: Do not generate documentation for files with no comments.
 public struct DocumentOptions {
     public let allModules: Bool
     public let spmModule: String?
@@ -41,13 +42,14 @@ public struct DocumentOptions {
     public let tableOfContents: Bool
     public let xcodeArguments: [String]
     public let reproducibleDocs: Bool
+    public let skipEmpty: Bool
 
     public init(allModules: Bool, spmModule: String?, moduleName: String?,
                 linkBeginningText: String = "", linkEndingText: String = ".md",
                 inputFolder: String, outputFolder: String,
                 minimumAccessLevel: AccessLevel = .public, includeModuleNameInPath: Bool = false,
                 clean: Bool = false, collapsibleBlocks: Bool = false, tableOfContents: Bool = false,
-                xcodeArguments: [String] = [], reproducibleDocs: Bool = false) {
+                xcodeArguments: [String] = [], reproducibleDocs: Bool = false, skipEmpty: Bool = false) {
         self.allModules = allModules
         self.spmModule = spmModule
         self.moduleName = moduleName
@@ -62,6 +64,7 @@ public struct DocumentOptions {
         self.tableOfContents = tableOfContents
         self.xcodeArguments = xcodeArguments
         self.reproducibleDocs = reproducibleDocs
+        self.skipEmpty = skipEmpty
     }
 }
 
@@ -157,7 +160,8 @@ public final class DocumentationGenerator {
     private func process(dictionary: SwiftDocDictionary) {
         let markdownOptions = MarkdownOptions(collapsibleBlocks: options.collapsibleBlocks,
                                               tableOfContents: options.tableOfContents,
-                                              minimumAccessLevel: options.minimumAccessLevel)
+                                              minimumAccessLevel: options.minimumAccessLevel,
+                                              skipEmpty: options.skipEmpty)
 
         if let value: String = dictionary.get(.kind), let kind = SwiftDeclarationKind(rawValue: value) {
             if kind == .struct, let item = MarkdownObject(dictionary: dictionary, options: markdownOptions) {

Sources/SourceDocsLib/DocumentationGenerator/Elements/MarkdownEnum.swift

@@ -34,7 +34,7 @@ struct MarkdownEnum: SwiftDocDictionaryInitializable, MarkdownConvertible {
                     let first = substructure.first else {
                         return nil
                 }
-                return MarkdownEnumCaseElement(dictionary: first)
+                return MarkdownEnumCaseElement(dictionary: first, options: options)
             }
             properties = structure.compactMap { MarkdownVariable(dictionary: $0, options: options) }
             methods = structure.compactMap { MarkdownMethod(dictionary: $0, options: options) }
@@ -43,6 +43,11 @@ struct MarkdownEnum: SwiftDocDictionaryInitializable, MarkdownConvertible {
             properties = []
             methods = []
         }
+
+        let topLevelDoc: String? = dictionary.get(.documentationComment)
+        guard !options.skipEmpty || topLevelDoc?.isEmpty == false || !cases.isEmpty || !properties.isEmpty || !methods.isEmpty else {
+            return nil
+        }
     }
 
     var tableOfContents: String {
@@ -107,9 +112,17 @@ struct MarkdownEnumCaseElement: SwiftDocDictionaryInitializable, MarkdownConvert
     let dictionary: SwiftDocDictionary
 
     init?(dictionary: SwiftDocDictionary) {
+        fatalError("Not supported")
+    }
+
+    init?(dictionary: SwiftDocDictionary, options: MarkdownOptions) {
         guard dictionary.isKind([.enumelement]) else {
             return nil
         }
+        let topLevelDoc: String? = dictionary.get(.documentationComment)
+        guard !options.skipEmpty || topLevelDoc?.isEmpty == false else {
+            return nil
+        }
         self.dictionary = dictionary
     }
 

Sources/SourceDocsLib/DocumentationGenerator/Elements/MarkdownMethod.swift

@@ -27,6 +27,10 @@ struct MarkdownMethod: SwiftDocDictionaryInitializable, MarkdownConvertible {
         guard dictionary.accessLevel >= options.minimumAccessLevel && dictionary.isKind(methods) else {
             return nil
         }
+        let topLevelDoc: String? = dictionary.get(.documentationComment)
+        guard !options.skipEmpty || topLevelDoc?.isEmpty == false else {
+            return nil
+        }
         self.dictionary = dictionary
         self.options = options
 

Sources/SourceDocsLib/DocumentationGenerator/Elements/MarkdownObject.swift

@@ -34,6 +34,11 @@ struct MarkdownObject: SwiftDocDictionaryInitializable, MarkdownConvertible {
             properties = []
             methods = []
         }
+
+        let topLevelDoc: String? = dictionary.get(.documentationComment)
+        guard !options.skipEmpty || topLevelDoc?.isEmpty == false || !properties.isEmpty || !methods.isEmpty else {
+            return nil
+        }
     }
 
     var elementType: String {

Sources/SourceDocsLib/DocumentationGenerator/Elements/MarkdownProtocol.swift

@@ -34,6 +34,11 @@ struct MarkdownProtocol: SwiftDocDictionaryInitializable, MarkdownConvertible {
             properties = []
             methods = []
         }
+
+        let topLevelDoc: String? = dictionary.get(.documentationComment)
+        guard !options.skipEmpty || topLevelDoc?.isEmpty == false || !properties.isEmpty || !methods.isEmpty else {
+            return nil
+        }
     }
 
     var markdown: String {

Sources/SourceDocsLib/DocumentationGenerator/Elements/MarkdownTypealias.swift

@@ -21,6 +21,10 @@ struct MarkdownTypealias: SwiftDocDictionaryInitializable, MarkdownConvertible {
         guard dictionary.accessLevel >= options.minimumAccessLevel && dictionary.isKind([.typealias]) else {
             return nil
         }
+        let topLevelDoc: String? = dictionary.get(.documentationComment)
+        guard !options.skipEmpty || topLevelDoc?.isEmpty == false else {
+            return nil
+        }
         self.dictionary = dictionary
         self.options = options
     }

Sources/SourceDocsLib/DocumentationGenerator/Elements/MarkdownVariable.swift

@@ -22,6 +22,10 @@ struct MarkdownVariable: SwiftDocDictionaryInitializable, MarkdownConvertible {
         guard dictionary.accessLevel >= options.minimumAccessLevel && dictionary.isKind(variables) else {
             return nil
         }
+        let topLevelDoc: String? = dictionary.get(.documentationComment)
+        guard !options.skipEmpty || topLevelDoc?.isEmpty == false else {
+            return nil
+        }
         self.dictionary = dictionary
         self.options = options
     }

Sources/SourceDocsLib/DocumentationGenerator/MarkdownIndex.swift

@@ -13,6 +13,7 @@ struct MarkdownOptions {
     var collapsibleBlocks: Bool
     var tableOfContents: Bool
     var minimumAccessLevel: AccessLevel
+    var skipEmpty: Bool
 }
 
 class MarkdownIndex {