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.

epage · 2026-02-11T16:32:58Z

src/cargo/core/compiler/unit_dependencies.rs

No test updates are in this commit. Either the tests in the previous commit are failing or there is a mismatch in expectations between the tests and this change.

This was marked as ready for review but this doesn't seem to be addressed.

Are there any questions about this has there have been more commits pushed without addressing this.

Apologies for the confusion! I did address the feedback:

Simplified the boolean expression from .require().is_ok() to .is_enabled() as you suggested

Verified all tests pass including the public-dependency tests

I should have been clearer in my commit messages about which feedback was being addressed. The code changes are now in place and working correctly. Is there anything specific you'd like me to clarify or improve further?

Unsure if this has been said in this thread before but we find it helpful for authors, reviewers, and the community when a PR has the tests added in their own commit before the fix with them passing, reproducing the existing behavior. The commit with the fix would then update the tests to still pass and show the new behavior. The diff would show how behavior changed.

Done in latest commit, just curious to confirm we do this before fix test + fix and updated test commit method for all the code changes PRs ?

Thanks

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.

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

epage · 2026-03-10T19:24:04Z

tests/testsuite/doc.rs

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


This test was added in the wrong commit

fixed, thanks

epage · 2026-03-10T19:25:57Z

tests/testsuite/doc.rs

+    // foo is the selected package
+    // bar is a direct dep of foo
+    // baz is a public dep of bar
+    // qux is a public dep of baz
+


better than comments like this is to name the packages for their role in the test, e.g.

foo -> selected

bar -> foo-dep

baz -> public-bar-dep

qux -> public-baz-dep

fixed, thanks

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