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...).
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?