Chapter 2 - "Generating a Random Number" Instructions in NOTE don't work (rand dependency not documented)

[Steve-Stearns-CardinalPeak]

• I have checked the latest main branch to see if this has already been fixed
• I have searched existing issues and pull requests for duplicates

URL to the section(s) of the book with this problem:
https://github.com/rust-lang/book/blob/main/src/ch02-00-guessing-game-tutorial.md

Description of the problem:
Following the instructions in the note, the documentation generated and opened does not include the documentation for the rand dependency. Per the discussion here: rust-lang/cargo#3805 It appears that it's not intended for the internal dependencies to be documented in that manner. I did try the approach shown in issue 3805 (cargo doc -p rand:0.3.23 --open) and that did allow me to see the rand documentation.

Suggested fix:
The note needs to be corrected to show the correct way which will successfully "build documentation provided by all of your dependencies locally and open it" as this would be very helpful.

It appears "cargo doc --all --open" works but I notice that the documentation for cargo doc deprecates this option in favor of --workspace which also appears to work.

[carols10cents]

Hm, that's really strange. So each listing has its complete project code in the listings directory in this repo. If I go into https://github.com/rust-lang/book/tree/8a0bb3c96e71927b80fa2286d7a5a5f2547c6aa4/listings/ch02-guessing-game-tutorial/listing-02-03, then run cargo doc --open, then I see this, which includes rand in the sidebar as mentioned in the note (I've added an arrow in this screenshot):

Could you please clone this repo, then cd listings/ch02-guessing-game-tutorial/listing-02-03, then run cargo doc --open and see if that shows rand in the sidebar? If it does, could you please compare your code to the complete project code in that directory to see if there are any differences?

If you run cargo doc --open in the listing-02-03 directory and you don't see rand in the sidebar, could you please let me know:

• Your operating system
• The output of rustc -vV
• The output of cargo -vV
• How you installed Rust

I don't think rust-lang/cargo#3805 is relevant here, and I'm not sure what you mean by "internal dependencies". This comment mentions that cargo doc --open doesn't document build dependencies, which are dependencies added to Cargo.toml under a [build-dependencies] table and only used in build.rs. That's not what Chapter 2 has instructed you to do, so I don't think that applies here.

I also am not sure how you got a workspace, because that's not something Chapter 2 uses either.

[Steve-Stearns-CardinalPeak]

This did turn out to be more interesting than I expected as it seemed so straight forward before, but no longer. I cloned the repo, ran the experiment and rand did show up in the sidebar. However, I then went back to my original ...\projects\guessing_game and reran cargo doc --open and, now, it also shows rand in the sidebar. So, one would think all was well if it wasn't for my experience of having previously followed the steps in the book (paper copy, third printing) and have it not work (repeatedly). In the interest of science (or whatever) I may remove rust from this computer tomorrow and repeat the install and the experiment and see if I can duplicate the previous failure. On the other hand, if you don't see any benefit in me attempting to duplicate the previous undesirable behavior (since is appears fixed in the current configuration) let me know and I will save myself the time.

[Steve-Stearns-CardinalPeak]

I'm going to assume at this point there was/is something screwed up in my installation. A clue to this affect is that running "rustup update" does not go well (failed to install component: 'rustfmt-preview-x86_64-pc-windows-msvc'... "error: could not remove 'component' directory: 'C:\Users\sstearns.rustup\toolchains\nightly-x86_64-pc-windows-msvc\share/doc/rust/html'" and, since at this stage I'm just trying to learn the basics and things mostly work for this book and the embedded book I'm just going to leave well enough alone. At some future date (and when I know more) I'll figure out how to redo the install from scratch and, if I remember, I'll rerun this test. Given all that, I'm closing the issue.

[Steve-Stearns-CardinalPeak]

work-in-progress update: I was forced to delete and reinstall rust after all and I reran the tests. This time around, with the cloned listings rand still appeared in the sidebar but with my original listing it does not. The listing directory upon which I did the comparison is listing-02-06 since it is at the same level of completion as mine.

OS is Windows 10 Enterprise

rustc -vV:
rustc 1.57.0 (f1edd0429 2021-11-29)
binary: rustc
commit-hash: f1edd0429582dd29cccacaf50fd134b05593bd9c
commit-date: 2021-11-29
host: x86_64-pc-windows-msvc
release: 1.57.0
LLVM version: 13.0.0

cargo -vV:
cargo 1.57.0 (b2e52d7ca 2021-10-21)
release: 1.57.0
commit-hash: b2e52d7cab0a286ee9fcc0c17510b1e72fcb53eb
commit-date: 2021-10-21
host: x86_64-pc-windows-msvc
libgit2: 1.3.0 (sys:0.13.23 vendored)
libcurl: 7.79.1-DEV (sys:0.4.49+curl-7.79.1 vendored ssl:Schannel)
os: Windows 10.0.18363 (Windows 10 Enterprise) [64-bit]

Rust install via: https://www.rust-lang.org/tools/install/

All execution is via powershell.

source file diff:

Cargo file diff:

[Steve-Stearns-CardinalPeak]

Doc page from the cloned listing:

Doc page from my original listing:

[carols10cents]

Thank you so much for doing this investigation and providing all this information! The diff between your project and the listing in this repo was especially useful. I'm able to reproduce by putting rand = 0.3.14 in a Cargo.toml, which I realize is what the print edition says to use. I'm investigating the problem further and trying to determine whether this is a bug with rand, cargo, rustdoc, or something else, and what remediations might be possible in each of these projects independent of the root cause. I'll update here when I have more info.

[carols10cents]

Ok, I think I've figured out that this is a cargo doc bug, which I've filed, so head over there if you're interested in all the details. I'm marking this as blocked and will update here when the Cargo bug is fixed. Thanks!

[Steve-Stearns-CardinalPeak]

Thanks for the update and I'm glad I was able to help.

[duanbiaowu]

1. edit Cargo.toml

rand = "0.4.6"

2. run command:

$ cargo doc --open