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

[ibilalkayy]

Hey @epage,

You're right that the examples did nothing wrong. It was executed through the command, but it didn't find the examples file and gave the error.

If a person just wants to open the file, then writing the --open would also be fine without --examples.

But now the problem arises, if the lib.rs or main.rs contains the docs but after executing the cargo doc command with the examples and open flags, should it open the documentation in the browser?

It has two parts.

Part No. 1

At this point, @profwpollock also has a strong point to open the browser and an error message should be given that the examples directory is missing.

If you agree on this point then we can change the message in which we can write that the docs of other files are provided except the examples and that's why

1. Remove the examples directory if it exists
2. OR fill the examples directory with docs

After some findings, I noticed that this behavior also exists in git where it takes the add, commit, and push commands. It adds and commits the changes successfully but when the wrong branch name is provided, then it does not push the code. All the things happen in just one line of command.

Here is the git commands to showcase:

Part No. 2:

Now if you want to keep the docs strict so that it gives you the error message without opening it in the browser. then it is also fine because

1. The user will be focused on the problem instead of getting distracted.
2. The user will be disturbed by switching from the browser to the code editor to see the result every time and maybe the user will say that the doc is generated but after coming back to the editor, he will notice that the example docs are not even present yet and there is an error.

I presented both points that could be implemented and I want to know what is your priority to implement. Let me know.

Thank you!

[weihanglo]

But now the problem arises, if the lib.rs or main.rs contains the docs but after executing the cargo doc command with the examples and open flags, should it open the documentation in the browser?

No. See #14776 (comment)
I would suggest being consistent and just fix the error message. Don't open the browser for a random URL from whatever on local cache that may eventually fail to find.

[ibilalkayy]

@weihanglo Well, I was not aware of the expected behavior of examples. Now, here are 2 points about which I am confused.

1. What if the lib contains the docs, will it be ignored if the examples are not provided?
2. What should be an error message if I am consistent on that message only?