Move definitions of documented option/flag names into DocumentedFlag

Author: d-ronnqvist

Plugins/Swift-DocC Convert/SwiftDocCConvert.swift

@@ -47,7 +47,7 @@ import PackagePlugin
             guard doccFeatures?.contains(.linkDependencies) == true else {
                 // The developer uses the combined documentation plugin flag with a DocC version that doesn't support combined documentation.
                 Diagnostics.error("""
-                Unsupported use of '--\(ParsedPluginArguments.enableCombinedDocumentation)'. \
+                Unsupported use of '\(DocumentedFlag.enableCombinedDocumentation.names.preferred)'. \
                 DocC version at '\(doccExecutableURL.path)' doesn't support combined documentation.
                 """)
                 return

Sources/SwiftDocCPluginUtilities/CommandLineArguments/ParsedPluginArguments.swift

@@ -17,27 +17,12 @@ struct ParsedPluginArguments {
 
     /// Creates a new plugin arguments container by extracting the known plugin values from a command line argument list.
     init(extractingFrom arguments: inout CommandLineArguments) {
-        enableCombinedDocumentation = arguments.extractFlag(named: Self.enableCombinedDocumentation).last ?? false
-        disableLMDBIndex = arguments.extractFlag(named: Self.disableLMDBIndex).last ?? false
-        verbose          = arguments.extractFlag(named: Self.verbose).last          ?? false
-        help             = arguments.extractFlag(named: Self.help).last             ?? false
+        enableCombinedDocumentation = arguments.extractFlag(.enableCombinedDocumentation) ?? false
+        disableLMDBIndex = arguments.extractFlag(.disableLMDBIndex)     ?? false
+        verbose          = arguments.extractFlag(.verbose)              ?? false
+        help             = arguments.extractFlag(named: Self.help).last ?? false
     }
 
-    /// A plugin feature flag to enable building combined documentation for multiple targets.
-    static let enableCombinedDocumentation = CommandLineArgument.Names(
-        preferred: "--enable-experimental-combined-documentation"
-    )
-    
-    /// A plugin feature flag to skip adding the `--emit-lmdb-index` flag, that the plugin adds by default.
-    static let disableLMDBIndex = CommandLineArgument.Names(
-        preferred: "--disable-indexing", alternatives: ["--no-indexing"]
-    )
-    
-    /// A plugin feature flag to enable verbose logging.
-    static let verbose = CommandLineArgument.Names(
-        preferred: "--verbose"
-    )
-    
     /// A common command line tool flag to print the help text instead of running the command.
     static let help = CommandLineArgument.Names(
         preferred: "--help", alternatives: ["-h"]
@@ -53,26 +38,18 @@ struct ParsedSymbolGraphArguments {
 
     /// Creates a new symbol graph arguments container by extracting the known plugin values from a command line argument list.
     init(extractingFrom arguments: inout CommandLineArguments) {
-        minimumAccessLevel     = arguments.extractOption(named: Self.minimumAccessLevel).last
-        skipSynthesizedSymbols = arguments.extractFlag(named: Self.skipSynthesizedSymbols).last
-        includeExtendedTypes   = arguments.extractFlag(named: Self.includeExtendedTypes, inverseNames: Self.excludeExtendedTypes).last
+        minimumAccessLevel     = arguments.extractOption(.minimumAccessLevel)
+        skipSynthesizedSymbols = arguments.extractFlag(.skipSynthesizedSymbols)
+        includeExtendedTypes   = arguments.extractFlag(.extendedTypes)
+    }
+}
+
+private extension CommandLineArguments {
+    mutating func extractFlag(_ flag: DocumentedFlag) -> Bool? {
+        extractFlag(named: flag.names, inverseNames: flag.inverseNames).last
     }
 
-    /// The minimum access level that the symbol graph extractor will emit symbols for.
-    static let minimumAccessLevel = CommandLineArgument.Names(
-        preferred: "--symbol-graph-minimum-access-level"
-    )
-    
-    /// The feature flag to omit synthesized symbols when extracting symbol information.
-    static let skipSynthesizedSymbols = CommandLineArgument.Names(
-        preferred: "--experimental-skip-synthesized-symbols"
-    )
-    
-    /// A pair of positive and negative feature flags to either include or exclude extended types when extracting symbol information.
-    static let includeExtendedTypes = CommandLineArgument.Names(
-        preferred: "--include-extended-types"
-    )
-    static let excludeExtendedTypes = CommandLineArgument.Names(
-        preferred: "--exclude-extended-types"
-    )
+    mutating func extractOption(_ flag: DocumentedFlag) -> String? {
+        extractOption(named: flag.names).last
+    }
 }

Sources/SwiftDocCPluginUtilities/DocumentedPluginFlags/DocumentedFlag.swift

@@ -28,8 +28,8 @@ extension DocumentedFlag {
     /// A plugin feature flag to enable building combined documentation for multiple targets.
     ///
     /// - Note: This flag requires that the `docc` executable supports ``Feature/linkDependencies``.
-    static let enableCombinedDocumentationSupport = Self(
-        names: ParsedPluginArguments.enableCombinedDocumentation,
+    static let enableCombinedDocumentation = Self(
+        names: .init(preferred: "--enable-experimental-combined-documentation"),
         abstract: "Create a combined DocC archive with all generated documentation.",
         discussion: """
             Experimental feature that allows targets to link to pages in their dependencies and that \
@@ -38,8 +38,8 @@ extension DocumentedFlag {
     )
 
     /// A plugin feature flag to skip adding the `--emit-lmdb-index` flag, that the plugin adds by default.
-    static let disableIndex = Self(
-        names: ParsedPluginArguments.disableLMDBIndex,
+    static let disableLMDBIndex = Self(
+        names: .init(preferred: "--disable-indexing", alternatives: ["--no-indexing"]),
         abstract: "Disable indexing for the produced DocC archive.",
         discussion: """
             Produces a DocC archive that is best-suited for hosting online but incompatible with Xcode.
@@ -48,7 +48,7 @@ extension DocumentedFlag {
 
     /// A plugin feature flag to enable verbose logging.
     static let verbose = Self(
-        names: ParsedPluginArguments.verbose,
+        names: .init(preferred: "--verbose"),
         abstract: "Increase verbosity to include informational output.",
         discussion: nil
     )
@@ -66,17 +66,17 @@ extension DocumentedFlag {
     /// - Note: This flag is only available starting from Swift 5.8. It should be hidden from the `--help` command for lower toolchain versions.
     /// However, we do not hide the flag entirely, because this enables us to give a more precise warning when accidentally used with Swift 5.7 or lower.
     static let extendedTypes = Self(
-        names: ParsedSymbolGraphArguments.includeExtendedTypes,
-        inverseNames: ParsedSymbolGraphArguments.excludeExtendedTypes,
-        abstract: "Control whether extended types from other modules are shown in the produced DocC archive. (default: \(Self.defaultExtendedTypesValue))",
+        names: .init(preferred: "--include-extended-types"),
+        inverseNames: .init(preferred: "--exclude-extended-types"),
+        abstract: "Control whether extended types from other modules are shown in the produced DocC archive. (default: --\(Self.defaultExtendedTypesValue ? "include" : "exclude")-extended-types)",
         discussion: "Allows documenting symbols that a target adds to its dependencies."
     )
 
     /// Exclude synthesized symbols from the generated documentation.
     ///
     /// `--experimental-skip-synthesized-symbols` produces a DocC archive without compiler-synthesized symbols.
     static let skipSynthesizedSymbols = Self(
-        names: ParsedSymbolGraphArguments.skipSynthesizedSymbols,
+        names: .init(preferred: "--experimental-skip-synthesized-symbols"),
         abstract: "Exclude synthesized symbols from the generated documentation.",
         discussion: """
             Experimental feature that produces a DocC archive without compiler synthesized symbols.
@@ -85,16 +85,16 @@ extension DocumentedFlag {
 
     /// The minimum access level that the symbol graph extractor will emit symbols for
     static let minimumAccessLevel = Self(
-        names: ParsedSymbolGraphArguments.minimumAccessLevel,
+        names: .init(preferred: "--symbol-graph-minimum-access-level"),
         abstract: "Include symbols with this access level or more. (default: public)",
         discussion: """
             Supported access level values are: `open`, `public`, `internal`, `private`, `fileprivate`
             """
     )
 
 #if swift(>=5.9)
-    private static let defaultExtendedTypesValue = ParsedSymbolGraphArguments.includeExtendedTypes.preferred
+    private static let defaultExtendedTypesValue = true
 #else
-    private static let defaultExtendedTypesValue = ParsedSymbolGraphArguments.excludeExtendedTypes.preferred
+    private static let defaultExtendedTypesValue = false
 #endif
 }

Sources/SwiftDocCPluginUtilities/HelpInformation.swift

@@ -44,13 +44,13 @@ public enum HelpInformation {
         }
 
         var supportedPluginFlags = [
-            DocumentedFlag.disableIndex,
+            DocumentedFlag.disableLMDBIndex,
             DocumentedFlag.verbose,
         ]
 
         let doccFeatures = (try? DocCFeatures(doccExecutable: doccExecutableURL)) ?? .init()
         if doccFeatures.contains(.linkDependencies) {
-            supportedPluginFlags.insert(DocumentedFlag.enableCombinedDocumentationSupport, at: 1)
+            supportedPluginFlags.insert(DocumentedFlag.enableCombinedDocumentation, at: 1)
         }
 
         for flag in supportedPluginFlags {