`cargo doc --open` error message is confusing when all targets are skipped

[profwpollock]

Problem

I use an alias for this command:

$ cargo doc -v --open --workspace --document-private-items --all-features --no-deps --examples

When first developing a new project, there are no examples yet. The output is:

warning: target filter `examples` specified, but no targets matched; this is a no-op
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.01s
error: no crates with documentation

So it is NOT a "no-op". I believe it should be. The warning alone is fine.

Proposed Solution

Instead of failing to provide crate documentation, it should create crate documentation even if there's no examples yet.

Notes

No response

[ehuss]

The Cargo team briefly looked at this, and agree that it would be helpful to update the error message to make it clearer that this is related to the --open flag. We probably want to keep the error itself, since the user explicitly asked to open a web browser, but if there are no crates, then there is nothing to open.

The no-op aspect is just an artifact that it is indeed a no-op to skip over a target selection flag that selects nothing (--examples), and that is handled generically for all commands at a very early stage. I suppose we could also reword that a little to say something else like "ignoring" or "skipping" or something like that, instead of "no-op". (Though sometimes people also get confused when saying "ignoring" when there are subtle differences between not passing the flag at all, so any rewording would need to be done with care.)

[profwpollock]

Actually the error is wrong. The crate does have documentation, just not examples (yet). As long as some crate documentation is produced, --examples should be a no-op and not produce any error; the warning is fine and the browser should open.

My workaround for this bug is to have two aliases, one with --examples and the other without.

Please revert the change in the title of this issue. Thanks for listening!

[weihanglo]

If there were some examples documented after running cargo doc --open --examples, the first example will be opened. That is the expected behavior of the --examples flag, as well as --example <ex> flag which will directly open a certain example.

In this case, there was no example, so no crate doc was produced. Not even the doc of the lib crate. Hence cargo was not able to open anything.

[profwpollock]

If that's the intended behavior, then I agree with rewording the error message. However, the warning is wrong in that case and should be removed.

But I wish the intended behavior would be to produce crate docs if any, and that --examples was indeed a no-op if there is documentation but no examples. It seems inconvenient to require a developer to use two slightly different commands to produce documentation during development.

[epage]

However, the warning is wrong in that case and should be removed.

How is the warning wrong?

But I wish the intended behavior would be to produce crate docs if any, and that --examples was indeed a no-op if there is documentation but no examples. It seems inconvenient to require a developer to use two slightly different commands to produce documentation during development.

In this case, cargo is doing exactly what you told it to do. imo we shouldn't be second guessing the user.

Personally, I've stopped using --open and instead click the file link that is printed (I switched from tmux to zellij because tmux stripped links at the time). If nothing else, I dislike that --open doesn't play well with my shell history in that I can't blindly run a command from my history but have to either add --open or remove it. Its also more consistent with other commands that would be awkward to have an --open, like cargo build --timings

[profwpollock]

The warning is wrong because it is not a no-op. It is an error and there's an error message produced already, so the erroneous warning is not only wrong but redundant.

The command with --examples along with --open may be working as intended. But that is most definitely not as I expected. I expect the browser to open if there's any crate documentation at all and produce a warning if --examples is specified but there are no examples. If that's not what cargo maintainers desire for the behavior, I understand. But in that case, the warning is incorrect and should be eliminated or at least reworded.

I will leave this issue to your judgment for resolution at this point. I do appreciate you taking the time to correspond with me and appreciate the great work you do. Even if you don't agree with me! :-)

[epage]

Two different things are being reported

• --examples did nothing warning
• No requested docs available to --open error

There is overlap (nothing). Whether something should be done depends on a couple of factors

• Whether the warning shows up for each set of flags passed in or only if none of the selected flags produce something (i.e. can we see the warning without the error)
• How well cargo internals can track all of the states that determine if the warning will show up at the same time knowing whether the error will show up and decide to suppress the warning