Test failures occur because comments are forwarded without being sanitized, due to Rust comments are executable in doctests.
If think in bigger picture
in contexts where comments are forwarded
I suspect that, in contexts where comments are forwarded, most macros do not sanitize them.
This may leads to compile failure.
This may also leads to running unsafe/untrust/unexpected code.
suggestion
Provide a capability similar to #[coverage(off)] attributes.
#[doctest(off)]
pub mod generated {
XXX::comments_are_executable_in_doctests!();
}
Code are 100% kept, but just simply avoid scope doctests, for forward comment scenario.
This way, the user of XXX’s macro takes on the responsibility of declaring which regions have doctest‑safe comments and which have doctest‑unsafe ones.
similar
The Rust compiler detects whether code generated by macros in crate XXX contains doctests, and if it does, requires the surrounding context to be wrapped in
pub mod generated {
unsafe {
XXX::comments_are_executable_in_doctests!();
};
}
In this way, easy to spot problem, but still need #[doctest(off)].
There’s no way to know if a comment is originally written by XXX or merely forwarded by XXX. If it’s forwarded, it’s also impossible to check whether it has been sanitized.
The obvious downside, however, is that in non‑forwarding scenarios, XXX developer maybe feel sad.
I don’t think this puts the responsibility in the right place. The tools that are forwarding comments should themselves be responsible for avoiding creating doctests — they just have no good way to do so without maintaining an exact duplicate of rustdoc’s Markdown parsing. So, the text itself should be tagged, something like:
#[doc(foreign = "the doc text here will not be interpreted as a test")]
which would be equivalent to #[doc = "the doc text here ..."] aka /// the doc text here ... except that a doctest cannot be declared by this part.
This works better with doc from mixed sources where some of it should be a test.
Another usefulness of more kinda of doc attributes: having non-markdown external docs render as plain prose. Currently I think you normally just have to codeblock these a lot of the time which doesn’t look great.