Allow certain directives in doc comments #591
Description
Feature Name
Some Directives in Doc Comments
Description
DocC currently disallows all directives in doc comments. There are reasons to allow some, such as @Snippet. @Snippet is a textual element that renders identically to a code block, so that would be reasonable to allow on symbols when there is a quick, canonical example to use an API.
Motivation
This feature request is motivated by allowing the @Snippet directive in doc comments, as was noted here: https://forums.swift.org/t/using-snippets-in-documentation-comments-not-possible/65046
I'll leave the total list of allowed directives to the implementor. There may be others that could be useful on symbol docs.
Importance
Code examples in doc comments are currently limited to Markdown code blocks. If snippets are a useful alternative to some code blocks, then it would be an improvement to allow them in doc comments as well.
Alternatives Considered
No response