ITADN

Documentation describes TriviaPiece.blockComment incorrectly (Markdown escaping issue)

#3185Openole 创建于 2025-11-08
bug
O
olecommented
### Description The rendered documentation for [`TriviaPiece.blockComment`](https://swiftpackageindex.com/swiftlang/swift-syntax/main/documentation/swiftsyntax/triviapiece/blockcomment(_:)) looks like this: > A developer block comment, starting with ‘/<em>’ and ending with ’</em>/’. Screenshot: <img width="663" height="421" alt="Image" src="https://github.com/user-attachments/assets/3a7e0d5e-a6fa-49fe-bf72-3a8205057df5" /> 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](https://github.com/swiftlang/swift-syntax/blob/02f8220bccfa03df68cc50631e11891c7ebcca0c/CodeGeneration/Sources/SyntaxSupport/Trivia.swift#L100): ```swift 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_
0 条评论