the first slice directive of a captionless Snippet is interpreted as a caption #157

New issue

Closed

opened 2025-10-14 15:49:44 -06:00 by navan · 0 comments

navan commented

2025-10-14 15:49:44 -06:00

Owner

Originally created by @tayloraswift on 6/8/2024

the parser always expects a caption to be present, so if there is no caption and the first line comment is a slice directive like // snippet.FOO, Unidoc will interpret that as the Snippet caption. this behavior is inconsistent with DocC.

fixing this will effectively mean that /snippet\.[\S]+/ constitutes a banned string for Snippet captions. that’s probably less surprising than interpreting the directive as caption text.

*Originally created by @tayloraswift on 6/8/2024* the parser always expects a [caption](https://github.com/apple/swift-evolution/blob/main/proposals/0356-swift-snippets.md#writing-a-snippet) to be present, so if there is no caption and the first line comment is a slice directive like `// snippet.FOO`, Unidoc will interpret that as the Snippet caption. this behavior is inconsistent with DocC. fixing this will effectively mean that `/snippet\.[\S]+/` constitutes a banned string for Snippet captions. that’s probably less surprising than interpreting the directive as caption text.