Only document reachable APIs with `cargo doc` by ojuschugh1 · Pull Request #16603 · rust-lang/cargo

ojuschugh1 · 2026-02-08T17:47:19Z

What does this PR try to resolve?

Fixes #2025

Adds support for documenting only direct dependencies when using the public-dependency feature. Currently cargo doc generates docs for all transitive dependencies, which creates a lot of noise. With this change, when -Zpublic-dependency is enabled, only direct deps and their public deps get documented.

Backward compatible - without the flag everything works as before.

rustbot · 2026-02-08T17:51:39Z

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: @ehuss, @epage, @weihanglo
@ehuss, @epage, @weihanglo expanded to ehuss, epage, weihanglo
Random selection from ehuss, epage, weihanglo

tests/testsuite/doc_direct_deps.rs

epage · 2026-02-09T14:49:08Z

tests/testsuite/doc_direct_deps.rs

+                pub_dep = { version = "0.0.1", public = true }
+                priv_dep = { version = "0.0.1", public = false }
+                priv_dep_with_dep = "0.0.1"
+            "#,


This is checking the mixed case for direct deps and not transitive deps. Is that intentional or did you meant for these to be indirect?

And what is it we are trying to get out of the mixed test vs other tests added?

And what is it we are trying to get out of the mixed test vs other tests added?

Could you help me understand the role of this test?

@ojuschugh1 there are outstanding questions on this

tests/testsuite/doc_direct_deps.rs

epage · 2026-02-09T14:52:01Z

src/cargo/core/compiler/unit_dependencies.rs

Currently cargo doc generates docs for all transitive dependencies, which creates a lot of noise.

This allows library authors to control their documentation surface by
marking which dependencies are part of their public API.

The reason is that indirect private deps have no impact on the reader of the docs since they cannot be used and this can dramatically speed up documentation builds, especially with packages like windows-sys in a dependency tree

src/cargo/core/compiler/unit_dependencies.rs

tests/testsuite/doc_direct_deps.rs

ojuschugh1 · 2026-02-10T03:25:24Z

I have addressed your comments and feedback, kindly please review it and let me know @epage , after that i will make the commits proper.

thanks

ranger-ross · 2026-02-10T13:51:40Z

@ojuschugh1 Would you mind cleaning up the commits to be atomic? (mentioned in the contributor guide)

Atomic commits aren't just for Git history, they make it easier for reviewers to review changes.

src/cargo/core/compiler/unit_dependencies.rs

tests/testsuite/doc.rs

ojuschugh1 · 2026-03-08T08:45:44Z

Hi @epage , Gentle reminder could you kindly please reivew it, when you get a moment.

Thanks

tests/testsuite/doc.rs

src/cargo/core/compiler/unit_dependencies.rs

tests/testsuite/doc.rs

epage · 2026-03-10T17:11:37Z

src/cargo/core/compiler/unit_dependencies.rs

+        let should_doc_dep = if is_member || !public_deps_enabled {
+            true


Should this be is_member or is_root?

If I have

workspace members selected and skipped

selected has a private dependency on skipped

I run cargo doc -p selected

Should we document the dependencies of skipped?

Either way, we should have a test for this.

I think there is a hole in that example. We document dependencies by default, so the private status of skipped is irrelevant. Some layers might be needed to make the use case correct.

Added a test doc_workspace_member_private_dep for this. Using is_member - workspace members get their deps documented regardless of how another member depends on them.

But is that the behavior we want?

I have renamed is_root to is_user_selected (backed by root_pkg_ids in State), which more precisely captures the intent: these are packages explicitly selected by the user (e.g. via -p), not just workspace members. The filter now only applies to deps of non-user-selected packages.

root is the term we use through the compilation process.

backed by root_pkg_ids in State

bcx has roots which is the Units that are a root

tests/testsuite/doc.rs

epage · 2026-03-10T17:16:40Z

tests/testsuite/doc.rs

+}
+
+#[cargo_test(nightly, reason = "public-dependency feature is unstable")]
+fn doc_with_private_dependency() {


we should call out that this is a transitive private dependency

Looks like this is still outstanding

tests/testsuite/doc.rs

ojuschugh1 force-pushed the fix-doc-direct-deps-2025 branch from 12fa44b to e7d5853 Compare February 8, 2026 17:50

ojuschugh1 marked this pull request as ready for review February 8, 2026 17:51

rustbot added the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 8, 2026

rustbot assigned weihanglo Feb 8, 2026