Skip to content

Commit

Permalink
fixed the error message for a user to open the crate (#14969)
Browse files Browse the repository at this point in the history
### What does this PR try to resolve?

This PR is resolving an
[issue](#14776 (comment))
where `cargo doc --open --examples` does not give a clear message when
the examples file is given to it.

I changed the message from `no crates with documentation` in the
[cargo_doc.rs](https://github.com/rust-lang/cargo/blob/58b2d609ece6bd0333e4d0f63a024fe3dd350b4b/src/cargo/ops/cargo_doc.rs#L62)
and
[doc.rs](https://github.com/rust-lang/cargo/blob/58b2d609ece6bd0333e4d0f63a024fe3dd350b4b/tests/testsuite/doc.rs#L1504)
to `requested crate documentation is not available to open`. Now it
becomes easy for the user to understand what they're missing.

 Fixes #14776

### How should we test and review this PR?

Here is the command through which you can test this change:

`cargo test SNAPSHOTS=overwrite -- doc::open_no_doc_crate`

<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:

* If this is your first contribution, read "Cargo Contribution Guide"
first:
  https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
  https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
  https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:

https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.

### What does this PR try to resolve?

Explain the motivation behind this change.
A clear overview along with an in-depth explanation are helpful.

You can use `Fixes #<issue number>` to associate this PR to an existing
issue.

### How should we test and review this PR?

Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.

If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests

### Additional information

Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->
  • Loading branch information
epage authored Dec 19, 2024
2 parents 71678a4 + 871e281 commit efaaa0c
Show file tree
Hide file tree
Showing 2 changed files with 6 additions and 5 deletions.
9 changes: 5 additions & 4 deletions src/cargo/ops/cargo_doc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -56,10 +56,11 @@ pub fn doc(ws: &Workspace<'_>, options: &DocOptions) -> CargoResult<()> {
let compilation = ops::compile(ws, &options.compile_opts)?;

if options.open_result {
let name = &compilation
.root_crate_names
.get(0)
.ok_or_else(|| anyhow::anyhow!("no crates with documentation"))?;
let name = &compilation.root_crate_names.get(0).ok_or_else(|| {
anyhow::anyhow!(
"cannot open specified crate's documentation: no documentation generated"
)
})?;
let kind = options.compile_opts.build_config.single_requested_kind()?;

let path = path_by_output_format(&compilation, &kind, &name, &options.output_format);
Expand Down
2 changes: 1 addition & 1 deletion tests/testsuite/doc.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1501,7 +1501,7 @@ fn open_no_doc_crate() {
.with_status(101)
.with_stderr_data(str![[r#"
[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
[ERROR] no crates with documentation
[ERROR] cannot open specified crate's documentation: no documentation generated
"#]])
.run();
Expand Down

0 comments on commit efaaa0c

Please sign in to comment.