rustdoc: module flag to prevent code blocks without a lang item from counting as rust

[Lokathor]

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.

[GuillaumeGomez]

I'm not a big fan of the idea...

[Lokathor]

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]

Because unless stated as non-rust code block, a code block should always be tested.

[Lokathor]

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]

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-cmark can make the difference between the two kinds of codeblocks. If not, we'll apply this option to all codeblocks.

[QuietMisdreavus]

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 their Event enum to allow us to tell the difference.

[QuietMisdreavus]

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]

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 doctest that 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]

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.