rust-lang / rust-lang/rust

Library documentation being created despite `lib.doc = false` setting

Open
#117,286 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug T-rustdoc
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

The tetromino crate has the following settings:
https://github.com/d-e-s-o/tetromino/blob/fb5b5e05d7cfe08d71a8490f50d40d3be5e8078c/Cargo.toml#L29-L31

The lib.doc field, specifically, is documented as:

The doc field indicates whether or not the target is included in the documentation generated by cargo doc by default.

When I build the documentation locally it seems to work reasonably fine: I don't see anything from lib.rs in said documentation:
screenshot-2023-10-27_08-09-09

However, after publishing this crate, documentation looks different:
screenshot-2023-10-27_08-10-44

Namely, I see only stuff from there. I am confused by this behavior. Is that because it's a crate with both a main and a lib? But why the divergence between local and remote? What is docs.rs doing differently?

Does it have to do with this clause? (which really should not apply here because both are named differently, actually)

Note: The binary will be skipped if its name is the same as the lib target.

If so, then, again, why the divergence? I'd really wish for things to be testable locally and then have the same effect everywhere.

Can somebody comment on the expected behavior, please?

Meta

rustc --version --verbose:

rustc 1.73.0-nightly (cc66ad468 2023-10-03) (gentoo)
binary: rustc
commit-hash: cc66ad468955717ab92600c770da8c1601a4ff33
commit-date: 2023-10-03
host: x86_64-unknown-linux-gnu
release: 1.73.0-nightly
LLVM version: 17.0.2

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the target settings in Cargo.toml and compare local cargo doc output with the published docs.rs tetromino_impl documentation. Determine why lib.doc = false produces different results remotely and identify the expected behavior for crates containing both a binary and a library.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
build-system, documentation
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.