Replace @Comment blocks with HTML comments

[amartini51]

This reduces the places where content in the comment causes DocC to silently mis-parse the comment and content after it.

The markdown parser for DocC first parses plain markdown syntax, and then identifies places where the @Comment { } syntax delimits blocks. That means it tries to parse the content of a comment as markdown first, and then later it gets turned into a comment. The parsing of HTML style comments happens as part of the first stage, which makes it less fragile.

Using the DocC syntax for comments, a lot of the issues seem to come from } appearing in commented-out in code listings, or from other places where part of the comment is being interpreted as markdown and preventing the later DocC parsing pass from treating that content as a comment, or in some causes causing content after it to be missing. Using the HTML comment syntax, the --> arrow used in comment-out formal grammar conflicts with the end-of-comment marker, which I worked around by changing them to a -> arrow. We can probably delete most or all of the commented-out formal grammar blocks, which seem to date back to the original drafting of the book's grammar.

[amartini51]

Between switching to HTML comments and working around the DocC parsing issue triggered by lines that start with @ these source changes make the following changes in the rendered output:

• Advanced Operators: Hides a swifttest comment after "For a complete list of how Swift transforms builder syntax"
• Attributes: Keeps the "Subsequent release renames MyProtocol" as part of the bulleted list item
• Attributes: Keeps the list items under Result Transformations as one list, rather than several lists one after another
• Concurrency: Hides the sleep-in-toy-code swifttest comment, renders the "Sendable Types" section instead of silently dropping it, hides the actors swifttest comment, and hides the actors-implicitly-sendable swifttest comment.
• A Swift Tour: Hides the alternate "Would you like a jelly baby?" example.
• Methods: Hides the commented out example under Method Binding
• Opaque Types: Hides the commented out example at the end of the file
• Protocols: Hides a comment in a note box

[amartini51]

@swift-ci Please build.

[amartini51]

@swift-ci Please test.