Allow certain directives in doc comments

[bitjammer]

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