Fix directive parsing bug in articles

Articles currently don’t support having a directive
as the first item of the discussion. This resolves the issue
while maintaining compatibility with Metadata, Comment, and
DeprecationSummary blocks.

Author: ethan-kusters

Sources/SwiftDocC/Model/DocumentationMarkup.swift

@@ -142,12 +142,17 @@ struct DocumentationMarkup {
                     abstractSection = AbstractSection(paragraph: firstParagraph)
                     return
                 } else if let directive = child as? BlockDirective {
-                    // Found deprecation notice in the abstract.
                     if directive.name == DeprecationSummary.directiveName {
+                        // Found deprecation notice in the abstract.
                         deprecation = MarkupContainer(directive.children)
+                        return
+                    } else if directive.name == Comment.directiveName || directive.name == Metadata.directiveName {
+                        // These directives don't affect content so they shouldn't break us out of
+                        // the automatic abstract section.
+                        return
+                    } else {
+                        currentSection = .discussion
                     }
-                    // Skip other block like @Comment and so on.
-                    return
                 } else if let _ = child as? HTMLBlock {
                     // Skip HTMLBlock comment.
                     return

Tests/SwiftDocCTests/Model/DocumentationMarkupTests.swift

@@ -77,13 +77,17 @@ class DocumentationMarkupTests: XCTestCase {
             My abstract __content__.
             """
             let expected = """
-            Text "My abstract "
-            Strong
-            └─ Text "content"
-            Text "."
+            BlockDirective name: "Directive"
+            └─ BlockDirective name: "NestedDirective"
+            Paragraph
+            ├─ Text "My abstract "
+            ├─ Strong
+            │  └─ Text "content"
+            └─ Text "."
             """
             let model = DocumentationMarkup(markup: Document(parsing: source, options: .parseBlockDirectives))
-            XCTAssertEqual(expected, model.abstractSection?.content.map({ $0.detachedFromParent.debugDescription() }).joined(separator: "\n"))
+            XCTAssertNil(model.abstractSection)
+            XCTAssertEqual(expected, model.discussionSection?.content.map({ $0.detachedFromParent.debugDescription() }).joined(separator: "\n"))
         }
 
         // Directives in between sections