Repository: apple/swift-docc (swift)

Issue:
Docc does not deal well with inline <!-- --> comments if they are first after the h1
### Description

Since we cannot add `@Comment` we need to use `<!-- -->` comments in docc markdown files.

Often the first few lines of a docc file under active development may be comment lines, like so:

```md
# ``Example``

<!-- FIXME: update docs when #23232323 is done -->

Provides a nice example...

## Hello world
```

---

The issue is that docc does not understand that the "_first line that is not empty_" actually is `Provides a nice example...` and thus the "subtitle" when referring to ``Example`` from other places, like a:

```

## Topics

### Articles

- <doc:Introduction>
- <doc:Example>
```

results in an empty "subtitle" for the Example:

![Screenshot 2022-07-25 at 18 41 03](https://user-images.githubusercontent.com/120979/180747590-14761cf6-d1d2-4d16-954b-b316166a419d.png)


### Checklist

- [ ] 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

But it should have been:

![Screenshot 2022-07-25 at 18 41 53](https://user-images.githubusercontent.com/120979/180747751-18fe5805-2ab2-424a-b94e-c14bea6c114e.png)


### Actual behavior

_No response_

### Steps To Reproduce

Explained example situation above

### Swift-DocC Version Information

5.7

### Swift Compiler Version Information

_No response_

Pull request description:
<!--
If you're opening a PR to cherry-pick a change for a release branch, use this template instead:
https://github.com/apple/swift-docc/blob/main/.github/PULL_REQUEST_TEMPLATE/CHERRY_PICK.md
-->

Bug/issue #, if applicable:


## Summary

Close #344  

## Testing

Steps:
1. Create a Swift Package and add documentation2. 
2. In a Article file, add the following text: 
```
# Example

<!--Line a-->

Line b

## Overview

Test
```
3. Compile the package and get the symbol-graph path. 
4. Run `swift-docc preview xx/DemoKit.docc --additional-symbol-graph-dir xx/DemoKit.build/symbol-graph` to see the effect

## 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
- [x] Updated documentation if necessary

Patch:
diff --git a/Sources/SwiftDocC/Model/DocumentationMarkup.swift b/Sources/SwiftDocC/Model/DocumentationMarkup.swift
index 63df0546bb..9ea16abf21 100644
--- a/Sources/SwiftDocC/Model/DocumentationMarkup.swift
+++ b/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,
diff --git a/Sources/SwiftDocC/Semantics/Article/Article.swift b/Sources/SwiftDocC/Semantics/Article/Article.swift
index c82effb140..e0e41c6898 100644
--- a/Sources/SwiftDocC/Semantics/Article/Article.swift
+++ b/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


Test patch:
diff --git a/Tests/SwiftDocCTests/Model/DocumentationMarkupTests.swift b/Tests/SwiftDocCTests/Model/DocumentationMarkupTests.swift
index a68e85ebba..82f74e5446 100644
--- a/Tests/SwiftDocCTests/Model/DocumentationMarkupTests.swift
+++ b/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 {