Correctly document updated parameters

Co-authored-by: Sofía Rodríguez <sofia_rodriguez@apple.com>

Author: d-ronnqvist

Sources/SwiftDocCPluginUtilities/CommandLineArguments/CommandLineArguments.swift

@@ -35,11 +35,11 @@ public struct CommandLineArguments {
 
     // MARK: Extract
 
-    /// Extracts the values for the command line option with the given names.
+    /// Extracts the values for the given command line option.
     ///
     /// Upon return, the arguments list no longer contains any elements that match any spelling of this command line option or its values.
     ///
-    /// - Parameter names: The names of a command line option.
+    /// - Parameter option: The command line option to extract values for.
     /// - Returns: The extracted values for this command line option, in the order that they appear in the arguments list.
     public mutating func extract(_ option: CommandLineArgument.Option) -> [String] {
         var values = [String]()
@@ -71,13 +71,11 @@ public struct CommandLineArguments {
         return values.reversed() // The values are gathered in reverse order
     }
 
-    /// Extracts the values for the command line flag with the given names.
+    /// Extracts the values for the command line flag.
     ///
     /// Upon return, the arguments list no longer contains any elements that match any spelling of this command line flag.
     ///
-    /// - Parameters:
-    ///   - positiveNames: The positive names for a command line flag.
-    ///   - negativeNames: The negative names for this command line flag, if any.
+    /// - Parameter flag: The command line flag to extract values for.
     /// - Returns: The extracted values for this command line flag.
     public mutating func extract(_ flag: CommandLineArgument.Flag) -> [Bool] {
         let positiveNames = flag.names
@@ -98,18 +96,16 @@ public struct CommandLineArguments {
 
     /// Inserts a command line option into the arguments list unless it already exists.
     /// - Parameters:
-    ///   - argument: The command line option to insert.
-    ///   - matchOptionWithAnyValue: If `true`, an option argument will be considered a match even
+    ///   - option: The command line option to insert.
+    ///   - value: The value for this option.
     /// - Returns:  `true` if the argument was already present in the arguments list; otherwise, `false`.
     @discardableResult
     public mutating func insertIfMissing(_ option: CommandLineArgument.Option, value: String) -> Bool {
         remainingOptionsOrFlags.appendIfMissing(.init(option, value: value))
     }
 
     /// Inserts a command line flag into the arguments list unless it already exists.
-    /// - Parameters:
-    ///   - argument: The command line flag to insert.
-    ///   - matchOptionWithAnyValue: If `true`, an option argument will be considered a match even
+    /// - Parameter flag: The command line flag to insert.
     /// - Returns:  `true` if the argument was already present in the arguments list; otherwise, `false`.
     @discardableResult
     public mutating func insertIfMissing(_ flag: CommandLineArgument.Flag) -> Bool {
@@ -121,10 +117,10 @@ public struct CommandLineArguments {
         remainingOptionsOrFlags.insert(rawArgument, at: 0)
     }
 
-    /// Inserts a command line argument into the arguments list, overriding any existing values.
+    /// Inserts a command line option with a new value into the arguments list, overriding any existing values.
     /// - Parameters:
-    ///   - argument: The command line argument (flag or option) to insert.
-    ///   - newValue: The new value for this command line argument.
+    ///   - option: The command line option to insert.
+    ///   - newValue: The new value for this option.
     /// - Returns: `true` if the argument was already present in the arguments list; otherwise, `false`.
     @discardableResult
     public mutating func overrideOrInsert(_ option: CommandLineArgument.Option, newValue: String) -> Bool {
@@ -160,7 +156,7 @@ private extension ArraySlice<String> {
         }
     }
 
-    /// Checks if the slice contains the given argument (flag or argument).
+    /// Checks if the slice contains the given argument (flag or option).
     func contains(_ argument: CommandLineArgument) -> Bool {
         let names = argument.names
         guard case .option(let value, .arrayOfValues) = argument.kind else {

Sources/SwiftDocCPluginUtilities/DocumentedPluginFlags/DocumentedArgument.swift

@@ -6,9 +6,9 @@
 // See https://swift.org/LICENSE.txt for license information
 // See https://swift.org/CONTRIBUTORS.txt for Swift project authors
 
-/// A documented command-line flag for the plugin.
+/// A documented command-line argument for the plugin.
 ///
-/// This may include some flags that the plugin forwards to the symbol graph extract tool or to DocC.
+/// This may include some arguments (flags or options) that the plugin forwards to the symbol graph extract tool or to DocC.
 struct DocumentedArgument {
     /// A command line argument (flag or option) that is wrapped with documentation.
     enum Argument {
@@ -29,10 +29,10 @@ struct DocumentedArgument {
         }
     }
 
-    /// A short user-facing description of this flag.
+    /// A short user-facing description of this argument (flag or option).
     var abstract: String
 
-    /// An expanded user-facing description of this flag.
+    /// An expanded user-facing description of this argument (flag or option).
     var discussion: String?
 
     init(flag: CommandLineArgument.Flag, abstract: String, discussion: String? = nil) {
@@ -85,7 +85,7 @@ extension DocumentedArgument {
 // MARK: Symbol graph flags
 
 extension DocumentedArgument {
-    /// Include or exclude extended types in documentation archives.
+    /// A plugin feature flag to either include or exclude extended types in documentation archives.
     ///
     /// Enables/disables the extension block symbol format when calling the dump symbol graph API.
     ///
@@ -100,7 +100,7 @@ extension DocumentedArgument {
         discussion: "Allows documenting symbols that a target adds to its dependencies."
     )
 
-    /// Exclude synthesized symbols from the generated documentation.
+    /// A plugin feature flag to exclude synthesized symbols from the generated documentation.
     ///
     /// `--experimental-skip-synthesized-symbols` produces a DocC archive without compiler-synthesized symbols.
     static let skipSynthesizedSymbols = Self(

Sources/SwiftDocCPluginUtilities/ParsedArguments.swift

@@ -139,72 +139,72 @@ struct ParsedArguments {
 enum DocCArguments {
     /// A fallback value for the bundle display name, if the documentation catalog doesn't specify one or if the build has no symbol information.
     ///
-    /// The plugin defines this name so that it can pass a default value for older versions of `docc` which require this.
+    /// The plugin defines this option so that it can pass a default value for older versions of `docc` which require this.
     static let fallbackDisplayName = CommandLineArgument.Option(
         preferred: "--fallback-display-name"
     )
 
     /// A fallback value for the bundle identifier, if the documentation catalog doesn't specify one or if the build has no symbol information.
     ///
-    /// The plugin defines this name so that it can pass a default value for older versions of `docc` which require this.
+    /// The plugin defines this option so that it can pass a default value for older versions of `docc` which require this.
     static let fallbackBundleIdentifier = CommandLineArgument.Option(
         preferred: "--fallback-bundle-identifier"
     )
 
     /// A fallback value for the "module kind" display name, if the documentation catalog doesn't specify one.
     ///
-    /// The plugin defines this name so that it can pass a default value when building documentation for executable targets.
+    /// The plugin defines this option so that it can pass a default value when building documentation for executable targets.
     static let fallbackDefaultModuleKind = CommandLineArgument.Option(
         preferred: "--fallback-default-module-kind"
     )
 
     /// A directory of symbol graph files that DocC will use as input when building documentation.
     ///
-    /// The plugin defines this name so that it can pass a default value.
+    /// The plugin defines this option so that it can pass a default value.
     static let additionalSymbolGraphDirectory = CommandLineArgument.Option(
         preferred: "--additional-symbol-graph-dir"
     )
 
     /// Configures DocC to include a LMDB representation of the navigator index in the output.
     ///
-    /// The plugin defines this name so that it can pass this flag by default.
+    /// The plugin defines this flag so that it can pass this flag by default.
     static let emitLMDBIndex = CommandLineArgument.Flag(
         preferred: "--emit-lmdb-index"
     )
 
     /// The directory where DocC will write the built documentation archive.
     ///
-    /// The plugin defines this name so that it can intercept it and support building documentation for multiple targets within one package build command.
+    /// The plugin defines this option so that it can intercept it and support building documentation for multiple targets within one package build command.
     static let outputPath = CommandLineArgument.Option(
         preferred: "--output-path",
         alternatives: ["--output-dir", "-o"]
     )
 
     /// A DocC feature flag to enable support for linking to documentation dependencies.
     ///
-    /// The plugin defines this name so that it can specify documentation dependencies based on target dependencies when building combined documentation for multiple targets.
+    /// The plugin defines this flag so that it can specify documentation dependencies based on target dependencies when building combined documentation for multiple targets.
     static let enableExternalLinkSupport = CommandLineArgument.Flag(
         preferred: "--enable-experimental-external-link-support"
     )
 
     /// A DocC flag that specifies a dependency DocC archive that the current build can link to.
     ///
-    /// The plugin defines this name so that it can specify documentation dependencies based on target dependencies when building combined documentation for multiple targets.
+    /// The plugin defines this option so that it can specify documentation dependencies based on target dependencies when building combined documentation for multiple targets.
     static let externalLinkDependency = CommandLineArgument.Option(
         preferred: "--dependency",
         kind: .arrayOfValues
     )
 
     /// A DocC flag for the "merge" command that specifies a custom display name for the synthesized landing page.
     ///
-    /// The plugin defines this name so that it can specify the package name as the display name of the default landing page when building combined documentation for multiple targets.
+    /// The plugin defines this option so that it can specify the package name as the display name of the default landing page when building combined documentation for multiple targets.
     static let synthesizedLandingPageName = CommandLineArgument.Option(
         preferred: "--synthesized-landing-page-name"
     )
 
     /// A DocC flag for the "merge" command that specifies a custom kind for the synthesized landing page.
     ///
-    /// The plugin defines this name so that it can specify "Package" as the kind of the default landing page when building combined documentation for multiple targets.
+    /// The plugin defines this option so that it can specify "Package" as the kind of the default landing page when building combined documentation for multiple targets.
     static let synthesizedLandingPageKind = CommandLineArgument.Option(
         preferred: "--synthesized-landing-page-kind"
     )