Documentation should make it clear where to put `doctest!`

[robinst]

I was adding this crate to my library like this:

tests/readme.rs:

use doc_comment::doctest;

doctest!("../README.md");

And I added an error into the code in README to see if it would fail. But cargo test succeeded.

What actually worked was adding this to src/lib.rs instead:

#[cfg(doctest)]
use doc_comment::doctest;

#[cfg(doctest)]
doctest!("../README.md");

It would be good if the documentation made it very clear where to add the code. Or was I missing something else?

[GuillaumeGomez]

This seems highly surprising. You can see the source code of the macro here. So I think the issue lies outside of this crate at this point...

[robinst]

Alright, I've created a minimal repo to reproduce here: https://github.com/robinst/test-doc-comment

Can you clone and run cargo test and see if it succeeds or fails?

My Rust version is 1.47.0 if that matters.

[GuillaumeGomez]

I just realized: you need to add #[cfg(doctest)] because doc-comment is in your dev-dependencies (as it should). All other troubles are from cargo I think. It should fail in case you run cargo test.

[robinst]

Doesn't help: https://github.com/robinst/test-doc-comment/commit/8ac8c8feb96c7c2567a351f8214aa0bc55552177

Note, adding this to tests/readme.rs doesn't make it fail either:

/// ```
/// assert_eq!("foo", "bar");
/// ```
fn foo() {}

So I think the problem is that doctests in integration tests are not run at all. It just needs to be documented.

[GuillaumeGomez]

Ah ok! Now I get your issue. Yes, tests are handled completely separately and rustdoc doesn't know about them. Can you please open an issue on https://github.com/rust-lang/rust and ask for documentation about this please? (and tag me on it so I can send a fix shortly).

[robinst]

Done: https://github.com/rust-lang/rust/issues/79587

But also, I think the docs for this crate (doc-comment) should mention it as well.