Difference between `cargo doc` and `cargo rustdoc`

Question

According to doc.rust-lang.org

• cargo rustdoc

build[s] a package's documentation, using specified custom flags

• cargo doc

build[s] a package's documentation

What is the difference between the two? From what I understand cargo rustdoc is just like cargo doc, but it allows for more lints—for instance:

#![deny(rustdoc::broken_intra_doc_links)]

Is this correct? Oddly enough, cargo rustdoc will also fail in certain situations where cargo doc doesn't. For instance

some/folder on some-branch [$!] via 🦀 v1.60.0-nightly
❯ cargo doc
    Finished dev [unoptimized + debuginfo] target(s) in 0.53s

some/folder on some-branch [$!] via 🦀 v1.60.0-nightly
❯ cargo rustdoc
error: manifest path `some/folder/Cargo.toml` is a virtual manifest, but this command requires running against an actual package in this workspace

Also, cargo doc does not support adding the -D option, whereas cargo rustdoc does.

❯ cargo doc -- -D rustdoc::broken_intra_doc_links
error: Found argument '-D' which wasn't expected, or isn't valid in this context

USAGE:
    cargo doc [OPTIONS]

For more information try --help

Ekg

It looks like rustdoc is for building a single target's docs, whereas doc is for building a whole package's docs. Not sure when you'd ever want the former over the latter. – Scourge

Answer 1

Their relationship is like between cargo build and cargo rustc: cargo doc performs all the usual work, for an entire workspace, including dependencies (by default). cargo rustdoc allows you to pass flags directly to rustdoc, and only works for a single crate.

Here is the execution code for cargo rustdoc. Here is the code for cargo doc. The only differences is that cargo rustdoc always specify to not check dependencies while cargo doc allows you to choose (by default it does, but you can specify the flag --no-deps), and that cargo rustdoc allows you to pass flags directly to rustdoc with the flags after the --.

Deyo