@DeprecationSummary not having effect for some symbols

[anferbui]

Bug/issue #, if applicable: Closes #932, rdar://70056350.

Summary

Fixes a bug where the @DeprecationSummary directive would have no effect if a symbol had multiple lines of documentation comments in its source, like so:

/// I am adding some amazing documentation for my new struct.
///
/// ## Overview
///
/// In fact it's so cool, that it even needs some markdown.
public struct ExampleDeprecated {}

The root cause of the issue was that the @DeprecatedSummary directive would only take effect when used in the "Abstract" section of the markup.

When using the default merging strategy for documentation extension files (append), documentation extension content is added after all the existing documentation comments, resulting in something like:

I am adding some amazing documentation for my new struct.

## Overview

In fact it's so cool, that it even needs some markdown.

@DeprecationSummary {
    This symbol is deprecated.
}

This would make the @DeprecationSummary directive be in the Discussion section, not the Abstract, so it would be ignored. This made it impossible to override the deprecation summary from the documentation extension file for any symbols which had multiple lines of documentation comments. (It worked fine if the symbol has no source documentation or only one line of source documentation).

This PR makes it so that the @DeprecationSummary can be parsed in both the Abstract and Discussion sections.

Dependencies

N/A.

Testing

You need the following setup:

• A symbol with multiple lines of documentation in the source code
• A documentation extension file which uses the @DeprecationSummary directive, for example.

Example DocC bundle:
TestPackage.docc.zip

Steps:

1. Download example bundle
2. Run docc preview TestPackage.docc
3. Go to http://localhost:8080/documentation/testpackage/exampledeprecated and verify that the symbol is marked as deprecated.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

• Added tests
• Ran the ./bin/test script and it succeeded
• [ ] Updated documentation if necessary Not necessary

Verification

Unit testing
Added unit tests to DocumentationMarkupTests and DeprecationSummaryTests .

[1703/1703] Testing SwiftDocCTests.SynchronizationTests/testBlockingWithLock
=> Checking for unacceptable language… okay.
=> Checking license headers… okay.
=> Validating scripts in bin subdirectory… okay

Site rendering

Before	After

[anferbui]

@swift-ci please test

[d-ronnqvist]

LGTM

[d-ronnqvist]

nit: using XCTUnwrap is a more succinct way to assert that a value is non-nil

Suggested change

	guard let renderNode = translator.visit(symbol) as? RenderNode else {
	XCTFail("Could not compile the node")
	return
	}
	let renderNode = try XCTUnwrap(translator.visit(symbol) as? RenderNode)

[anferbui]

Thank you, I copy&pasted previous tests and failed to notice this. Reworked the whole file to use XCTUnwrap where appropriate!

[anferbui]

@swift-ci please test