Add solution to remove invalid metadata directives in documentation c…

[Konikz]

Bug/issue #, if applicable: #1111

Summary

This PR addresses issue #1111 by adding a solution to remove invalid metadata directives in documentation comments. When a user encounters a warning about an invalid metadata directive in a documentation comment, they will now see a solution that allows them to remove the directive with a single click, rather than having to manually edit the source code.

Dependencies

None. This PR doesn't depend on any other changes.

Testing

To test this functionality, you can use the following test content:

@Metadata {
    @DisplayName("Custom Name")
    @TechnologyRoot
}

Steps:

1. Add the test content to a documentation comment in your Swift code.
2. Build the documentation with DocC.
3. You should see warnings about invalid metadata directives in documentation comments.
4. Each warning should have a solution that allows you to remove the directive.
5. Click on the solution to remove the directive.

The test case testInvalidMetadataDirectivesInDocumentationCommentHaveSolution in Tests/SwiftDocCTests/Semantics/MetadataTests.swift verifies that:

• The correct number of problems are generated
• Each problem has a solution
• The solution has the correct summary and replacement

Checklist

• Added tests
• Ran the ./bin/test script and it succeeded ()
• Updated documentation if necessary

[d-ronnqvist]

@swift-ci please test

[d-ronnqvist]

Thanks for opening this PR.

The code generally looks good but there's a compiler error in the added test.

[d-ronnqvist]

possibleSolutions is non-optional so the XCTAssertNotNil check isn't necessary and the optional chaining in the other assertions fail to compile.

XCTAssertEqual(problem.possibleSolutions?.count, 1)
                                        `- error: cannot use optional chaining on non-optional value of type '[Solution]'

[d-ronnqvist]

FYI: since you're checking a few different values of the same first solution, you can require that the first solution exist once using XCTUnwrap and use the unwrapped value in the later test assertions.

However, this is just a matter of style and preference. Not a requested change. I'm happy with both styles here, whichever you find more readable.

[d-ronnqvist]

I think that this test assertion will fail because the string it's expecting doesn't put single quotes around the directive name like the solution does.

FYI: A completely different style that some will find more readable and some will find less readable could be to move the summary assertion out of the for-loop and assert on both messages together:

XCTAssertEqual(problems.map(\.possibleSolutions.first?.summary), [
    "Remove this 'DisplayName' directive.",
    "Remove this 'TechnologyRoot' directive.",
])

(I believe that the order of the problems will be stable based on the order that they appear in the test content. Otherwise you can unwrap the first solution and sort the mapped summaries.)

[Konikz]

@d-ronnqvist working on rectifying the issue