Cargo: For a package where a library and a binary have the same name, have `cargo doc` ignore the bin

Created on 30 Jul 2017 · 14Comments · Source: rust-lang/cargo

Ok, so it's a common pattern (and one we use a bunch in the book) to have both a src/lib.rs and a src/main.rs and have the binary crate use the library crate.

Unfortunately, when you run cargo doc in one of these projects, you get:

error: cannot document a package where a library and a binary have the same name. Consider
renaming one or marking the target as `doc = false`

Those suggestions work; moving src/main.rs to src/bin/main.rs also lets you cargo doc the library.

But this is Yet Another Thing, with 3 options on how to fix it with no clear "best" option for a beginner (I went with moving main into bin for the book, I think that's easiest).

And since documenting binary crates isn't valid anyway, are there any reasons why, in this situation with a lib and a bin crate with the same name, cargo doc couldn't ignore the binary crate and happily document the lib crate?

Command-doc

Source

carols10cents

👍4

All 14 comments

I think you can actually document a binary target, which is the origin for this error (there's no way to document a library and a binary with the same name w/ rustdoc today).

One possibility is to also use:

[[bin]]
name = "crate-name-here"
doc = false

I think? (albeit that's not great either)

alexcrichton on 31 Jul 2017

👍1

I had no idea you could document a binary target.

steveklabnik on 31 Jul 2017

One possibility is to also use:

Yeah, that's what the error message suggests (it's not wrapping in my description will fix)

carols10cents on 31 Jul 2017

I suppose I could see the reason behind it if you only had a binary crate and not a library crate in the same project, but imo the current behavior is more surprising/annoying than ignoring the binary if there's a bin+lib with the same name? Perhaps we could change this error to a warning and recommend renaming one if you want to document both?

carols10cents on 31 Jul 2017

Note that I don't necessarily see a reason to persist the current behavior, I'd be fine changing it.

alexcrichton on 31 Jul 2017

From a user's perspective, my original reason for filing https://github.com/rust-lang/book/issues/847 was that I felt it was important that cargo doc "just works" out of the box without friction. Given that putting lib.rs and main.rs in the same directory seems to be a commonly adopted idiom (even if the book could be adjusted not to use it), I'd vote for some solution that allows the default behavior to produce something useful. This could mean ignoring bin, or ignoring it while emitting a warning, or producing documentation containing both in the output.

scode on 1 Aug 2017

👍1

Original motivating issue: https://github.com/rust-lang/cargo/issues/318

alexcrichton on 10 Aug 2017

Ok! What we discussed in the cargo team meeting today is:

In this situation, it seems fine to ignore the binary crate and only document the library crate. No errors, and also no warnings, since this is a valid state to want to remain in and would be annoying if we kept warning you about it.
We should make it so that cargo doc --bins and cargo doc --bin [cratename] also work in this situation when you DO want to document the binary. Currently these result in the same error:

 $ cargo doc --bins
error: cannot document a package where a library and a binary have the same name. Consider renaming one or marking the target as `doc = false`
$ cargo doc --bin cratename
error: cannot document a package where a library and a binary have the same name. Consider renaming one or marking the target as `doc = false`

For packages that only have a binary crate, cargo doc should document the binary crate.
- OR we could have this error and say "no library crate found, run cargo doc --bin cratename if you want to document the binary crate?
The current manpage docs for cargo doc say:

If the --package argument is given, then SPEC is a package id specification
which indicates which package should be documented. If it is not given, then the
current package is documented. For more information on SPEC and its format, see
the cargo help pkgid command.

We should change this to say "If it is not given, then the current library package is documented" or similar.

Does this accurately represent what was discussed @rust-lang/cargo?

carols10cents on 10 Aug 2017

Sounds accurate to me!

OR we could have this error and say "no library crate found, run cargo doc --bin cratename if you want to document the binary crate?

I'd say that by default Cargo should just document everything it can, so it wouldn't recommend you pass --bin in this situation.

alexcrichton on 10 Aug 2017

I'd say that by default Cargo should just document everything it can, so it wouldn't recommend you pass --bin in this situation.

Yeah, I was just thinking about this workflow:

Create src/main.rs that contains some documentation, running cargo doc displays said documentation
Decide src/main.rs is getting too big, split it out into src/main.rs that still has some documentation and src/lib.rs that also has some documentation
Run cargo doc, only the documentation in src/lib.rs is displayed, the docs in src/main.rs mysteriously don't show up anymore

How do we guide the user to getting their src/main.rs docs to show up again? If they've had to run cargo doc --bin whatever since the beginning, at least they'd ostensibly know about that....

carols10cents on 10 Aug 2017

I've hit this annoying issue multiple times now. It feels a bit odd that even cargo doc --lib spits out this error, shouldn't it just ignore the binary in that case? I don't like to clutter my Cargo.toml with an otherwise unnecessary binary section, but I cannot build any documentation if I don't...

jonas-schievink on 20 Aug 2017

How is this fixed? I just installed rust following the steps in https://doc.rust-lang.org/book/2018-edition/ch02-00-guessing-game-tutorial.html and cargo doc gives this same error message right out of the box.