cargo test wants to execute English language prose from bindgen as a doc test

[filmil]

Problem
Cargo test tries to execute English language prose in the comments of the rust file generated by bindgen as doc tests, just because the header documentation of the original code
had some indented passages.

It seems very inconvenient that code would not compile because of something going on in the comments. Especially when what's in the comments is misintepreted by the toolchain.

Steps

1. I have src/lib.rs and bindgen/lib.rs. bindgen/lib.rs is generated by bindgen, lib.rs is the hand-written part.
2. src/lib.rs contains an `include!("../bindgen/lib.rs") to keep hand-written and generated parts separate.
3. Running cargo test tries to interpret comments in ../bindgen/lib.rs as rust tests. They are just english prose that happens to be indented. Error is seen below.
4. It is possible to add #![doc(tests(ignore))], but it's a top level directive. Which means if you do add it to both files, then the compiler will complain that src/lib.rs has this directive at a non-top-level
   place. If you add it just to one, the compiler will complain about the other file.

error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found `are`
 --> src/../bindgen/lib.rs:4322:8
  |
3 | Fields are placed for optimal alignment on
  |        ^^^ expected one of 8 possible tokens here

error: aborting due to previous error

Couldn't compile the test.

Possible Solution(s)
There could be a flag to forbid doc test execution for files that I don't want treated this way.

Notes

Output of cargo version:
cargo 1.38.0-nightly (e853aa9 2019-08-09)

[filmil]

FWIW, there is a bindgen flag --no-doc-comments that may help...

[ehuss]

This is an issue with bindgen creating comments with indentation which is treated as a code block. Code blocks always default to rust in rustdoc.

Regardless, this isn't an issue for cargo. Either bindgen could rewrite the comments (unlikely) or rustdoc could provide an escape hatch (see rust-lang/rust#59867). If you want to disable doc tests entirely for the crate, doctest=false can be set in Cargo.toml. There are also some workarounds noted in rust-lang/rust-bindgen#1313.