Adds support for comments in warning about extraneous content found after a link in task group item (#706)

Adds support for comments in warning about extraneous content found after a link in task group item

rdar://115321138

Author: mayaepps

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

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 })