Add a documentation catalog to PackagePlugin.

Sources/PackagePlugin/ArgumentExtractor.swift

@@ -10,20 +10,41 @@
 //
 //===----------------------------------------------------------------------===//
 
-/// A rudimentary helper for extracting options and flags from a string list representing command line arguments. The idea is to extract all known options and flags, leaving just the positional arguments. This does not handle well the case in which positional arguments (or option argument values) happen to have the same name as an option or a flag. It only handles the long `--<name>` form of options, but it does respect `--` as an indication that all remaining arguments are positional.
+/// A structure that extracts options and flags from a string list representing command-line arguments.
+///
+/// `ArgumentExtractor` leaves positional arguments, and extracts option arguments and flags.
+/// It supports long-form option names with two hyphens (for example, `--verbose`), and treats `--` as an indicator that all remaining arguments are positional.
+///
+/// > Warning:
+/// > `ArgumentExtractor` doesn't detect situations in which positional arguments or optional parameters have the same name as a long option argument.
 public struct ArgumentExtractor {
     private var args: [String]
     private let literals: [String]
 
-    /// Initializes a ArgumentExtractor with a list of strings from which to extract flags and options. If the list contains `--`, any arguments that follow it are considered to be literals.
+    /// Initializes an argument with a list of strings from which to extract flags and options.
+    ///
+    /// If the list contains `--`, `ArgumentExtractor` treats any arguments that follow it as positional arguments.
+    ///
+    /// - Parameter arguments: The list of command-line arguments.
     public init(_ arguments: [String]) {
         // Split the array on the first `--`, if there is one. Everything after that is a literal.
         let parts = arguments.split(separator: "--", maxSplits: 1, omittingEmptySubsequences: false)
         self.args = Array(parts[0])
         self.literals = Array(parts.count == 2 ? parts[1] : [])
     }
 
-    /// Extracts options of the form `--<name> <value>` or `--<name>=<value>` from the remaining arguments, and returns the extracted values.
+    /// Extracts the value of a named argument from the list of remaining arguments.
+    ///
+    /// A named argument has one of these two forms:
+    /// * `--<name>=<value>`
+    /// * `--<name> <value>`
+    ///
+    /// If this method detects an argument that matches the supplied name, it removes the argument and its value from the list of arguments and returns the value.
+    /// The same name can appear in the list of arguments multiple times, and this method returns a list of all matching values.
+    ///
+    /// - Parameters:
+    ///   - name: The option name to extract the value for.
+    /// - Returns: An array of values for the named option.
     public mutating func extractOption(named name: String) -> [String] {
         var values: [String] = []
         var idx = 0
@@ -49,7 +70,10 @@ public struct ArgumentExtractor {
         return values
     }
 
-    /// Extracts flags of the form `--<name>` from the remaining arguments, and returns the count.
+    /// Extracts options with the given name from the remaining arguments.
+    ///
+    /// - Parameter name: The option to search for. The method prefixes it with two hyphens. For example, pass `verbose` to extract the `--verbose` option.
+    /// - Returns: The number of matching options in the list of arguments.
     public mutating func extractFlag(named name: String) -> Int {
         var count = 0
         var idx = 0
@@ -66,12 +90,16 @@ public struct ArgumentExtractor {
         return count
     }
 
-    /// Returns any unextracted flags or options (based strictly on whether remaining arguments have a "--" prefix).
+    /// A list of unextracted flags or options.
+    ///
+    /// A flag or option is any argument that has the prefix `--` (two hyphens).
     public var unextractedOptionsOrFlags: [String] {
         return args.filter{ $0.hasPrefix("--") }
     }
 
-    /// Returns all remaining arguments, including any literals after the first `--` if there is one.
+    /// A list of all remaining arguments.
+    ///
+    /// If the arguments list contains the string `--`, then all arguments after it are included in this list even if they would otherwise match named flags or options.
     public var remainingArguments: [String] {
         return args + literals
     }