Repository: apple/swift-docc (swift)

Issue:
Warning about "Extraneous content found after a link in task group list item" should support comments
### Description

Pages are organized into a hierarchy using "topic sections". The links in each topic section is written as an unordered list of symbol links or documentation links. Each list item can only contain this link, no other content.

We have a warning when there is other content in the list item: 
> Extraneous content found after a link in task group list item

However, if the extra content is just a comment then it's not real content and it doesn't impact the topic section.

We should update the code that emits this warning to permit comments. 

One use case for adding a comment after a link in the topic curation is to explain what symbol a link with disambiguation refers to, for example
```md
- ``validate()-1hb4l`` <!-- mutating func validate() throws -->
```

### Checklist

- [X] If possible, I've reproduced the issue using the `main` branch of this package.
- [X] This issue hasn't been addressed in an [existing GitHub issue](https://github.com/apple/swift-docc/issues).

### Expected Behavior

A comment after a topic section item shouldn't raise a warning. 

### Actual behavior

A comment after a topic section item result in a "Extraneous content found after a link in task group list item" warning.

### Steps To Reproduce

In any file with symbols organized into topic sections, 
- add `<!-- this is a comment -->` at the end of one of the topic section list items.
- build documentation 


### Swift-DocC Version Information

f6b3b6bd8dfb42fbe5a6dd6eee448eb51f31f232

### Swift Compiler Version Information

```shell
swift-driver version: 1.87.1 Apple Swift version 5.9 (swiftlang-5.9.0.128.1 clang-1500.0.40.1)
Target: x86_64-apple-macosx13.0
```

Pull request:
Bug/issue #, if applicable: #679 
rdar://115321138

## Summary

This adds support for comments after task group list items. When extra content appears after a list item, there is a warning that:
> Extraneous content found after a link in task group list item

However, when a comment is added after a list item, this warning should not occur. This PR adds a check that the extra content is not a comment before creating the warning. 

## Dependencies

N/A

## Testing

Steps:
1. Add a comment in a task group after a link: 
```
- ``link`` <!-- This is a comment -->
```
2. Check there are no warnings

## Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

- [x] Added tests
- [x] Ran the `./bin/test` script and it succeeded
- [ ] Updated documentation if necessary

Patch:
diff --git a/Sources/SwiftDocC/Model/TaskGroup.swift b/Sources/SwiftDocC/Model/TaskGroup.swift
index 035f2244fa..4cbbd32495 100644
--- a/Sources/SwiftDocC/Model/TaskGroup.swift
+++ b/Sources/SwiftDocC/Model/TaskGroup.swift
@@ -93,6 +93,16 @@ struct ExtractLinks: MarkupRewriter {
                 guard let paragraph = item.child(at: 0) as? Paragraph,
                     paragraph.childCount >= 1 else { return true }
                 
+                // Check for trailing invalid content.
+                let containsInvalidContent = paragraph.children.dropFirst().contains { child in
+                    let isComment = child is InlineHTML
+                    var isSpace = false
+                    if let text = child as? Text {
+                        isSpace = text.string.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
+                    }
+                    return !(isComment || isSpace)
+                }
+                
                 switch paragraph.child(at: 0) {
                     case let link as Link:
                         // Topic link
@@ -114,7 +124,7 @@ struct ExtractLinks: MarkupRewriter {
                         links.append(link)
                         
                         // Warn if there is a trailing content after the link
-                        if paragraph.childCount > 1 {
+                        if containsInvalidContent {
                             problems.append(problemForTrailingContent(paragraph))
                         }
                         return false
@@ -123,7 +133,7 @@ struct ExtractLinks: MarkupRewriter {
                         links.append(link)
                         
                         // Warn if there is a trailing content after the link
-                        if paragraph.childCount > 1 {
+                        if containsInvalidContent {
                             problems.append(problemForTrailingContent(paragraph))
                         }
                         return false


Test patch:
diff --git a/Tests/SwiftDocCTests/Infrastructure/DocumentationCuratorTests.swift b/Tests/SwiftDocCTests/Infrastructure/DocumentationCuratorTests.swift
index 12c36a2e54..7071a34eeb 100644
--- a/Tests/SwiftDocCTests/Infrastructure/DocumentationCuratorTests.swift
+++ b/Tests/SwiftDocCTests/Infrastructure/DocumentationCuratorTests.swift
@@ -279,6 +279,10 @@ class DocumentationCuratorTests: XCTestCase {
             ### Extraneous list item content
             - <doc:MyKit/MyClass>.
             - <doc:MyKit/MyClass> ![](featured.png) and *more* content...
+            - <doc:MyKit/MyClass> @Comment { We (unfortunately) expect a warning here because DocC doesn't support directives in the middle of a line. }
+            - <doc:MyKit/MyClass>   <!-- This is a valid comment -->
+            - <doc:MyKit/MyClass> <!-- This is a valid comment --> but this is extra content :(
+            - <doc:MyKit/MyClass> This is extra content <!-- even if this is a valid comment -->
             ## See Also
             - <doc:MyKit/MyClass>
             - Blip blop!
@@ -324,11 +328,11 @@ class DocumentationCuratorTests: XCTestCase {
                 .filter({ $0.diagnostic.identifier == "org.swift.docc.UnexpectedTaskGroupItem" })
                 .compactMap({ $0.possibleSolutions.first?.replacements.first?.range })
                 .map({ "\($0.lowerBound.line):\($0.lowerBound.column)..<\($0.upperBound.line):\($0.upperBound.column)" }),
-            ["6:1..<6:13", "9:1..<9:20", "15:1..<15:13", "5:1..<5:13", "8:1..<8:20", "11:1..<11:13"]
+            ["6:1..<6:13", "9:1..<9:20", "19:1..<19:13", "5:1..<5:13", "8:1..<8:20", "11:1..<11:13"]
         )
         
-        // Verify the crawler emitted warnings for the 2 items with trailing content.
-        XCTAssertEqual(crawler.problems.filter({ $0.diagnostic.identifier == "org.swift.docc.ExtraneousTaskGroupItemContent" }).count, 2)
+        // Verify the crawler emitted warnings for the 5 items with trailing content.
+        XCTAssertEqual(crawler.problems.filter({ $0.diagnostic.identifier == "org.swift.docc.ExtraneousTaskGroupItemContent" }).count, 5)
         XCTAssertTrue(crawler.problems
             .filter({ $0.diagnostic.identifier == "org.swift.docc.ExtraneousTaskGroupItemContent" })
             .compactMap({ $0.diagnostic.source?.path })