Repository navigation
rustdoc: module flag to prevent code blocks without a lang item from counting as rust #59867
Description
So, I've got some code being generated by bindgen. The C source has doxygen doc comments in it, which bindgen faithfully converts over into doc comments. However, some of the doxygen content is indented with spaces (numbered lists and the like), so when converted into rustdoc it becomes a code block. These code blocks are picked up as "doctests" by cargo test, which then of course fail to build because they're not Rust code at all.
I'm told that, internally, this is all just code block elements by the time rustdoc sees it, you can't tell which code block was made via a backtick fence and which was made via indentation. However, you can tell if a lang was declared on the code block.
So what I need is an opt-in flag that you can declare module-wide (and children modules and such) so that any code block without a declared language is not treated as rust code by default, so then it won't become a doctest.
Activity
GuillaumeGomez commentedon Apr 11, 2019
I'm not a big fan of the idea...
Lokathor commentedon Apr 12, 2019
Can you say more about why not?
Keeping in mind that that I'm not asking for it to be a default, just to have it be available as something that a person can turn on if they want to turn it on.
GuillaumeGomez commentedon Apr 12, 2019
Because unless stated as non-rust code block, a code block should always be tested.
Lokathor commentedon Apr 12, 2019
If I explicitly type out an attribute flag at the top of a module, that says "ignore all code blocks in here that lack a language marker", perhaps something like
#![rustdoc::only_doctest_code_blocks_with_rust_lang]Then that seems fairly clearly "stated" to me.
GuillaumeGomez commentedon Apr 12, 2019
Like I said, I don't like the idea. But if other @rust-lang/rustdoc people are okay with it, I'll add it. We'll also need to check if
pulldown-cmarkcan make the difference between the two kinds of codeblocks. If not, we'll apply this option to all codeblocks.QuietMisdreavus commentedon Apr 12, 2019
Taking a quick look at
pulldown-cmark, it looks like it reports indented code blocks and fenced code blocks the same way, though it does differentiate between them internally. It's possible we could ask them to extend theirEventenum to allow us to tell the difference.QuietMisdreavus commentedon Apr 12, 2019
Speaking about the request generally, i'm of the opinion that we should allow the marker attribute that @Lokathor suggested. Accidental doc tests from indented code blocks were one of the biggest false positives when we initially migrated to pulldown, and in this kind of situation with generated code, it's worth providing an out. If we can add the check to make it only ignore indented code blocks, i'd say that's even better.
lopopolo commentedon Apr 13, 2019
I'm running into this same problem trying to build a sys crate for
mruby, an embedded Ruby interpreter. The headers contain indented code blocks that are Ruby code. For generated code, I don't want rust to do anything with the comments because I don't control their contents. It is conceivable that mruby would document their code samples with backticks and I wouldn't want Rust to execute those either.There is already a cargo config
doctestthat we can use to opt out of doc tests crate wide. I'd like a marker that I can use to limit the scope of this config to only the module containing the generated bindings.threema-danilo commentedon May 31, 2023
I'm also affected by this. We're generating code from protobuf types (using prost). The protobuf comments, sometimes containing indented markdown blocks, are converted to rustdoc comments. Unfortunately Rust's doctests try to interpret all those markdown blocks as Rust code (and in some occasions fail to do so with a compile-time error message when running
cargo test). And it appears that there is no way to work around the issue from the Rust side...In this case I can adjust the protocol specifications to satisfy Rust, but it would be fantastic if there were a way to disable rust doctest processing within a certain module.