Fix article abstract section issue (#347)

* Fix article abstract section issue

* Add @comment test for abstract

Author: Kyle-Ye

Sources/SwiftDocC/Model/DocumentationMarkup.swift

@@ -22,7 +22,7 @@ import Markdown
 /// # My Document
 /// ```
 /// ### Abstract
-/// The parser parses the abstract from the first leading paragraph in the markup after the title. If the markup doesn't start with a paragraph after the title heading, it's considered to not have an abstract.
+/// The parser parses the abstract from the first leading paragraph (skipping the comments) in the markup after the title. If the markup doesn't start with a paragraph after the title heading, it's considered to not have an abstract.
 /// ```
 /// # My Document
 /// An abstract shortly describing My Document.
@@ -146,6 +146,10 @@ struct DocumentationMarkup {
                     if directive.name == DeprecationSummary.directiveName {
                         deprecation = MarkupContainer(directive.children)
                     }
+                    // Skip other block like @Comment and so on.
+                    return
+                } else if let _ = child as? HTMLBlock {
+                    // Skip HTMLBlock comment.
                     return
                 } else {
                     // Only directives and a single paragraph allowed in an abstract,

Sources/SwiftDocC/Semantics/Article/Article.swift

@@ -31,7 +31,7 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
     ///   - metadata: An optional container for metadata that's unrelated to the article's content.
     ///   - redirects: An optional list of previously known locations for this article.
     init(markup: Markup?, metadata: Metadata?, redirects: [Redirect]?) {
-        let markupModel = markup.map({ DocumentationMarkup(markup: $0) })
+        let markupModel = markup.map { DocumentationMarkup(markup: $0) }
 
         self.markup = markup
         self.metadata = metadata

Tests/SwiftDocCTests/Model/DocumentationMarkupTests.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -158,6 +158,24 @@ class DocumentationMarkupTests: XCTestCase {
             XCTAssertEqual(expected, model.abstractSection?.content.map({ $0.detachedFromParent.debugDescription() }).joined(separator: "\n"))
         }
 
+        // Contains an HTMLBlock comment and a BlockDirective comment before the abstract
+        do {
+            let source = """
+            # Title
+            <!--Line a-->
+            @Comment{
+                Line b
+            }
+            Line c
+            ## Hello, world!
+            Discussion content.
+            """
+            let expected = """
+            Text \"Line c\"
+            """
+            let model = DocumentationMarkup(markup: Document(parsing: source, options: .parseBlockDirectives))
+            XCTAssertEqual(expected, model.abstractSection?.content.map{ $0.detachedFromParent.debugDescription() }.joined(separator: "\n"))
+        }
     }
 
     func testDeprecation() throws {