Repository: apple/swift-docc (swift)

Issue:
Link resolution fail warnings in comment section
### Description

Currently, when we try to build swift-book's docc documention, it will give us a lot of warnings.

https://github.com/apple/swift-book/issues/9

Some diagnostic is useful and is tracked to Github issues waiting to be fixed.

However some diagnostic seems useless and IMO should not emit such as "Link resolution fail warnings" in comment section.

I think swift-docc should not emit such diagnostic if the link is from the comment section or add a flag to silence such diagnostic.

<img width="1411" alt="image" src="https://user-images.githubusercontent.com/43724855/189511008-7a070f68-a65d-4522-b29b-f6bf6e173b78.png">

### 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

_No response_

### Actual behavior

_No response_

### Steps To Reproduce

_No response_

### Swift-DocC Version Information

_No response_

### Swift Compiler Version Information

_No response_

Pull request:
<!--
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: 

Close #377 

## Summary

Skip comment block link resolution

This will reduce the warning number of swift-book's build documentation from 63 to less than 20.

The remaining issues are:
- https://github.com/apple/swift-book/issues/1
- Actually misused links https://github.com/apple/swift-book/issues/36

eg.
swift-book try to reference `#### Switching Over Future Enumeration Cases` in Statements.md but swift-docc will only create anchor section for H2 and H3 not for H4.

https://github.com/apple/swift-docc/blob/5fe2d1331eba2243163366e4d25259b86a44e5db/Sources/SwiftDocC/Model/DocumentationNode.swift#L113-L124

> Note: If we enable to use hierarchy based link resolver, the warning will also emit the available children for we to look up.
```
/Users/kyle/Workspace/Github/swift-docc-project/swift-book/Sources/TSPL/TSPL.docc/ReferenceManual/Attributes.md:663:17: warning: Topic reference 'doc:Statements#Switching-Over-Future-Enumeration-Cases' couldn't be resolved. Reference at '/The-Swift-Programming-Language/Statements' can't resolve 'Switching-Over-Future-Enumeration-Cases'. Available children: Availability-Condition, Branch-Statements, Break-Statement, Compile-Time-Diagnostic-Statement, Compiler-Control-Statements, Conditional-Compilation-Block, Continue-Statement, Control-Transfer-Statements, Defer-Statement, Do-Statement, Fallthrough-Statement, For-In-Statement, Guard-Statement, If-Statement, Labeled-Statement, Line-Control-Statement, Loop-Statements, Repeat-While-Statement, Return-Statement, Switch-Statement, Throw-Statement, While-Statement.
```

## Dependencies

None

## Testing
There are 2 ways to verify the change
1. Revert the commit [Skip comment block link resolution](https://github.com/apple/swift-docc/pull/390/commits/11e0553b0e17d45638a79bd45338fa0484d90367) and run the tests.

The expected result is you'll get one test failure on the new test case

`testCommentArbitraryReference(): XCTAssertEqual failed: ("0") is not equal to ("3")`

3. Test the warning emitted by TSPL
```
preview
$(SWIFT_BOOK_REPO_PATH)/Sources/TSPL/TSPL.docc
--fallback-display-name SwiftDocC
--fallback-bundle-identifier org.swift.SwiftDocC 
--fallback-bundle-version 1.0.0
--index
--emit-fixits
--additional-symbol-graph-dir
$(SWIFT_BOOK_BUILD_PATH)/Build/Intermediates.noindex/tspl.build/Debug/TSPL.build/symbol-graph 
```

## 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/Semantics/MarkupReferenceResolver.swift b/Sources/SwiftDocC/Semantics/MarkupReferenceResolver.swift
index 31808c448f..f5785f7a2f 100644
--- a/Sources/SwiftDocC/Semantics/MarkupReferenceResolver.swift
+++ b/Sources/SwiftDocC/Semantics/MarkupReferenceResolver.swift
@@ -168,6 +168,8 @@ struct MarkupReferenceResolver: MarkupRewriter {
             } else {
                 return blockDirective
             }
+        case Comment.directiveName:
+            return blockDirective
         default:
             return defaultVisit(blockDirective)
         }


Test patch:
diff --git a/Tests/SwiftDocCTests/Semantics/MarkupReferenceResolverTests.swift b/Tests/SwiftDocCTests/Semantics/MarkupReferenceResolverTests.swift
new file mode 100644
index 0000000000..7601c52974
--- /dev/null
+++ b/Tests/SwiftDocCTests/Semantics/MarkupReferenceResolverTests.swift
@@ -0,0 +1,30 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 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
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import XCTest
+@testable import SwiftDocC
+import Markdown
+
+class MarkupReferenceResolverTests: XCTestCase {
+    func testArbitraryReferenceInComment() throws {
+        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        let source = """
+        @Comment {
+            ``hello`` and ``world`` are 2 arbitrary symbol links.
+            <doc:NOT-EXISTS-DESTINATION#UNKNOWN>
+            But since they are under a comment block, no reference resolve problem should be emitted.
+        }
+        """
+        let document = Document(parsing: source, options: [.parseBlockDirectives, .parseSymbolLinks])
+        var resolver = MarkupReferenceResolver(context: context, bundle: bundle, source: nil, rootReference: context.rootModules[0])
+        _ = resolver.visit(document)
+        XCTAssertEqual(0, resolver.problems.count)
+    }
+}