I've been doing some work with a tool which takes a language-independent schema spec, with doc comments, and generates Rust code with corresponding #[doc] attributes on the relevent items.
The problem is that the original source documentation is inconsistently formatted, but markdownish enough. It has indented sections which may or may not be intended to be code blocks, but if they are they're almost certainly not Rust.
This poses two problems:
it generates warnings for text which isn't Rust but is being parsed as Rust
it allows arbitrary code to be injected as doctest into a generated file which is otherwise derived from a non-Turing-complete schema (ie, someone could jokingly put a "nuke the world" code example in a comment which ends up being executed in tests)
I'd like a way to solve both of these by blanket ignoring all code blocks in the doc comments.
In principle I could pre-parse the text as markdown and convert all the apparent code blocks into ```text blocks, but it would be simpler to generate something like:
#[doc(codeblock="text")]
#[doc = "..."]
I can solve 2) with
#[cfg_attr(not(doctest), doc = ...)]
but it doesn't stop cargo doc from complaining about malformed Rust code (which I could suppress by adding doc to the cfg_attr at the cost of losing all the documentation...).
The codeblock="xxx" form is also generic and allows arbitrary code block attributes to be applied.
Or is there some way of handling this with the current set of rustdoc mechanisms?
Having a mechanism to force all code blocks in documentation to be treated as a certain type by default seems reasonable; that would make sense either on the item with the #[doc], or at the top level of a module applying to all documentation in the module.
I don't think any such mechanism exists today, but adding one makes sense.
Also, if you want to give examples of code that includes backquotes, you just need to use more than three backquotes in the surrounding delimiters. For instance, to write:
With a great markdown engine, you can do the same for inline code blocks as well, as ```` ```text ```` renders as ```text. Unfortunately, many sub-great existing markdown engines do actually support `` inline code blocks, but choke on ```, always treating it as a full code block.
Typing this post and counting ` was interesting.
unrendered
With a great markdown engine, you can do the same for inline code blocks as well, as ````` ```` ```text ```` ````` renders as ```` ```text ````. Unfortunately, many sub-great existing markdown engines do actually support ``` `` ``` inline code blocks, but choke on ```` ``` ````, always treating it as a full code block.
Typing this post and counting `` ` `` was interesting.
<details><summary>unrendered</summary>
<!-- error infinite recursion -->
</details>