Documentation describes TriviaPiece.blockComment incorrectly (Markdown escaping issue) #3185
Description
Description
The rendered documentation for TriviaPiece.blockComment looks like this:
A developer block comment, starting with ‘/’ and ending with ’/’.
Screenshot:
Note that the documentation shows the wrong tokens "/" and "/" for a block comment and renders the text in between in italics. The reason is apparently that the DocC Markdown renderer (correctly, from its perspective) interprets the asterisks in /* and */ as emphasis markers.
The fix would be to change the doc comment string in the let TRIVIAS array:
public let TRIVIAS: [Trivia] = [
…
Trivia(
name: "BlockComment",
comment: #"A developer block comment, starting with '/*' and ending with '*/'."#,
traits: [.comment]
),
…The comment should either use code voice (backticks) for the tokens or escape the asterisks with backslashes (which is the official Markdown way to escape special characters). I'd do this myself, but I thought I'd post here first because I don't know if such a change would interfere with other places where the comment field is used as plain text where Markdown formatting or escaping would be a problem.
Steps to Reproduce
No response