Cargo doc and doctests

[jacg]

1. cargo doc is a shorthand for rustdoc <with a bunch of useful options>
2. rustdoc --test
   a) runs the doctests
   b) injects boilerplate around the doctests

• Is there a way to get cargo doc to run the doctests?
• Is there a way to get cargo test to inject similar boilerplate to 2.b?
• If not, is there a way to exclude doctests from cargo test?

[kpreid]

@jacg

Is there a way to get cargo test to inject similar boilerplate to 2.b?

cargo test should run the doc-tests in the standard fashion, including the main wrapper and such. Are you seeing it fail?

[jacg]

@jacg

• [...] is there a way to exclude doctests from cargo test ?

One way is to add

[lib]
doctest = false

to Cargo.toml

It's still not clear to me whether it should be possible on the CLI.

[jacg]

@kpreid

cargo test should run the doc-tests in the standard fashion, including the main wrapper and such. Are you seeing it fail?

I was under the impression that cargo test was forcing me to add use::mycrate::thing_being_tested; to every test, while rustdoc --test was not.

But now I find that rustdoc --test fails tests that cargo test passes, complaining thus:

  |
3 | use abcde::watever...
  |     ^^^^^ maybe a missing crate `abcde`?

Clearly I'm getting myself very confused.

[kpreid]

I was confused about what you were seeing but I just went to try direct rustdoc out myself and consult the documentation you linked (thanks!) and the “useful options” Cargo passes include --crate-name.

By default, rustdoc assumes that the name of your crate is the same name as the .rs file. --crate-name lets you override this assumption with whatever name you choose.

So, you didn't say what exactly you passed to rustdoc, but I imagine you didn't specify --crate-name abcde. And, the filename to be passed is the crate root source file — so if you didn't specify src/lib.rs as the file, then you'd get a bunch of errors just trying to analyze the file, unless your code is very simple.

At this point, I think the question that needs to be asked is: for what purpose are you trying to use rustdoc instead of cargo test --doc? If it's just that

@jacg

I was under the impression that cargo test was forcing me to add use::mycrate::thing_being_tested; to every test, while rustdoc --test was not.

then it sounds much more likely that your previous attempt to use rustdoc wasn't running the tests at all. It's normal to have use in your doctests — or to write full paths. Remember, doctests are runnable examples — they're less usable as examples if the import path is hidden. (Though you can hide them with #, and I do that when writing more than one example in a single piece of documentation.)

[jacg]

Forgetting my circumstantial problems, would you agree that the following 3 points are standard or recommended practice?

1. Use cargo doc to build and cargo test (with implicit or explicit --doc) to test the documentation. Do not use rustdoc directly for either of these purposes.

2. Add explicit uses to the examples.

3. Hide them with # to avoid multiple repetitions of the same across many consecutive examples.

?

As for the boring, but nonetheless annoying to me, problems that I was having (thanks for following this up so diligently):

• I'm pretty confident that my previous attempt to use rustdoc was running the tests, because I deliberately made some fail, to verify this. But maybe I'm misremembering.

• I don't really want to use rustdoc instead of cargo test, I just wanted to work through the documentation from the very beginning, to strengthen my patchy knowledge, and was puzzled by the divergence. (From this perspective, it's a shame that the documentation mentions rustdoc at all: it seems that the preferred way to create and test the docs is with cargo rather than rustdoc. Having two tools for the same job, which are very similar yet different in behaviour, slowed me down considerably.)

• I suspect what happened was that in my toy example the crate name diverged from the file name, at some stage while I was already using cargo exclusively. cargo took this divergence in its stride, while rustdoc didn't, but I only noticed this after you replied and I went back to check what happens with rustdoc, only increasing my confusion.

[kpreid]

@jacg

Forgetting my circumstantial problems, would you agree that the following 3 points are standard or recommended practice?

1. Use cargo doc to build and cargo test (with implicit or explicit --doc ) to test the documentation. Do not use rustdoc directly for either of these purposes.

I'm not an expert — I've only really worked on one personal project. But no one else seems to be replying, so my experience is what you get. I've never found any use for running rustdoc directly — I didn't even know what its command like looked like until this thread. Every discussion of doctests I've read has been using cargo doc.

An analogy that makes sense to me: running rustdoc directly is much like running rustc directly. Sometimes there are uses for it, but in both cases you lose the benefit of the things Cargo sets up for you.

2. Add explicit uses to the examples.

I haven't noticed what is most common among library style, but if you take a look around the std documentation, all of its examples (that I've noticed) have visible uses.

3. Hide them with # to avoid multiple repetitions of the same across many consecutive examples.

That's something that is possible and I've done myself occasionally. I have no information about whether it is recommended or disrecommended by others.

I suspect what happened was that in my toy example the crate name diverged from the file name, at some stage while I was already using cargo exclusively. cargo took this divergence in its stride, while rustdoc didn't, but I only noticed this after you replied and I went back to check what happens with rustdoc , only increasing my confusion.

FYI, the crate name in a Cargo project is usually not the same as the file name. Normally you have a crate named after the package name of your choice (as set in Cargo.toml), and its file is src/lib.rs or src/main.rs. The only place you'd have a matching name is in the case of the multiple-binary layout, where src/bin/foo.rs auto-defines a binary crate named foo.