Fix a bug where targets with multiple dependencies was only passed one dependency

[d-ronnqvist]

Bug/issue #, if applicable: #97

Summary

This fixes an issue where the plugin would only pass one --dependency value when building combined documentation.

@sofiaromorales and I worked together on the initial fix and made some additional API refinements to the way that the plugin works with command line arguments to make it ensure that an option always has the same behavior at every call site and that an option can't accidentally be used as a flag or vice-versa.

After what Sofía and I worked on, I made some follow-up changes to use the Flag and Option types in more places, move the inverseNames into Flag, and use CommandLineArguments for the docc merge arguments to avoid that direct [String] manipulation.

Dependencies

None.

Testing

Build combined documentation for a Swift package where at least one of the targets has more than once source dependency. For example;

Modify IntegrationTests/Tests/Fixtures/TargetsWithDependencies to depend on the local version of the plugin:

- if FileManager.default.fileExists(atPath: "../swift-docc-plugin") {
      package.dependencies += [
-         .package(path: "../swift-docc-plugin"),
+         .package(path: "../../../.."),
      ]
- }

Then, run swift package generate-documentation --enable-experimental-combined-documentation --verbose and inspect the build log.

The docc convert call for the "Outer" target (which builds last because it depends on the other targets) should have two different --dependency flags passed to it;

• The absolute path to .build/plugins/Swift-DocC/outputs/intermediates/InnerFirst.doccarchive
• The absolute path to .build/plugins/Swift-DocC/outputs/intermediates/InnerSecond.doccarchive

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• [ ] Updated documentation if necessary Not applicable

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

Because we don't have a Swift 5.7 CI yet, I manually tested this with the swift:5.7-focal Docker image:

Swift version 5.7.3 (swift-5.7.3-RELEASE)
Target: aarch64-unknown-linux-gnu

[sofiaromorales]

Update comment to match function signature:

/// Extracts the values for the command line argument.
///
/// Upon return, the arguments list no longer contains any elements that match any spelling of this command line option or its values.
///
/// - Parameter option: The command line option.
/// - Returns: The extracted values for this command line argument, in the order that they appear in the arguments list.

[d-ronnqvist]

Fixed in 703f680

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

Thanks for suggesting all those corrections and improvements to the documentation. I applied them in 703f680 together with a few more along the same lines.