Skip to content

Commit 172fb93

Browse files
author
Ojus Chugh
committed
Add tests for documenting direct dependencies only
Add test coverage for issue #2025 to verify that cargo doc can selectively document dependencies based on public/private markers. Tests cover: - Backward compatibility (all deps documented without feature) - Public dependency chains (transitive public deps documented) - Private dependencies (transitive deps not documented) - Mixed public/private scenarios These tests verify the expected behavior before implementing the feature, ensuring we maintain backward compatibility.
1 parent e456e09 commit 172fb93

2 files changed

Lines changed: 243 additions & 0 deletions

File tree

‎tests/testsuite/doc_direct_deps.rs‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
//! Tests for documenting direct dependencies.
2+
3+
use crate::prelude::*;
4+
use cargo_test_support::registry::Package;
5+
use cargo_test_support::{project, str};
6+
7+
#[cargo_test]
8+
fn doc_direct_deps_only() {
9+
// Create a dependency chain: foo -> bar -> baz
10+
// Without public-dependency, all deps are documented for backward compat
11+
Package::new("baz", "0.0.1")
12+
.file("src/lib.rs", "pub fn baz() {}")
13+
.publish();
14+
15+
Package::new("bar", "0.0.1")
16+
.dep("baz", "0.0.1")
17+
.file("src/lib.rs", "extern crate baz; pub fn bar() {}")
18+
.publish();
19+
20+
let p = project()
21+
.file(
22+
"Cargo.toml",
23+
r#"
24+
[package]
25+
name = "foo"
26+
version = "0.0.1"
27+
edition = "2015"
28+
29+
[dependencies]
30+
bar = "0.0.1"
31+
"#,
32+
)
33+
.file("src/lib.rs", "extern crate bar; pub fn foo() {}")
34+
.build();
35+
36+
p.cargo("doc")
37+
.with_stderr_data(
38+
str![[r#"
39+
[UPDATING] `dummy-registry` index
40+
[LOCKING] 2 packages to latest compatible versions
41+
[DOWNLOADING] crates ...
42+
[DOWNLOADED] baz v0.0.1 (registry `dummy-registry`)
43+
[DOWNLOADED] bar v0.0.1 (registry `dummy-registry`)
44+
[DOCUMENTING] baz v0.0.1
45+
[CHECKING] baz v0.0.1
46+
[DOCUMENTING] bar v0.0.1
47+
[CHECKING] bar v0.0.1
48+
[DOCUMENTING] foo v0.0.1 ([ROOT]/foo)
49+
[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
50+
[GENERATED] [ROOT]/foo/target/doc/foo/index.html
51+
52+
"#]]
53+
.unordered(),
54+
)
55+
.run();
56+
57+
// With default behavior (no public-dependency), all deps are documented
58+
assert!(p.root().join("target/doc/foo/index.html").is_file());
59+
assert!(p.root().join("target/doc/bar/index.html").is_file());
60+
assert!(p.root().join("target/doc/baz/index.html").is_file());
61+
}
62+
63+
64+
#[cargo_test(nightly, reason = "public-dependency feature is unstable")]
65+
fn doc_with_public_dependency_feature() {
66+
// foo -> bar (public) -> baz (public)
67+
// baz should be documented since bar marks it as public
68+
69+
Package::new("baz", "0.0.1")
70+
.file("src/lib.rs", "pub fn baz() {}")
71+
.publish();
72+
73+
Package::new("bar", "0.0.1")
74+
.cargo_feature("public-dependency")
75+
.add_dep(
76+
cargo_test_support::registry::Dependency::new("baz", "0.0.1").public(true)
77+
)
78+
.file("src/lib.rs", "extern crate baz; pub fn bar() {}")
79+
.publish();
80+
81+
let p = project()
82+
.file(
83+
"Cargo.toml",
84+
r#"
85+
cargo-features = ["public-dependency"]
86+
87+
[package]
88+
name = "foo"
89+
version = "0.0.1"
90+
edition = "2015"
91+
92+
[dependencies]
93+
bar = { version = "0.0.1", public = true }
94+
"#,
95+
)
96+
.file("src/lib.rs", "extern crate bar; pub fn foo() {}")
97+
.build();
98+
99+
p.cargo("doc -Zpublic-dependency")
100+
.masquerade_as_nightly_cargo(&["public-dependency"])
101+
.with_stderr_data(
102+
str![[r#"
103+
[UPDATING] `dummy-registry` index
104+
[LOCKING] 2 packages to latest compatible versions
105+
[DOWNLOADING] crates ...
106+
[DOWNLOADED] baz v0.0.1 (registry `dummy-registry`)
107+
[DOWNLOADED] bar v0.0.1 (registry `dummy-registry`)
108+
[DOCUMENTING] baz v0.0.1
109+
[CHECKING] baz v0.0.1
110+
[DOCUMENTING] bar v0.0.1
111+
[CHECKING] bar v0.0.1
112+
[DOCUMENTING] foo v0.0.1 ([ROOT]/foo)
113+
[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
114+
[GENERATED] [ROOT]/foo/target/doc/foo/index.html
115+
116+
"#]]
117+
.unordered(),
118+
)
119+
.run();
120+
121+
// All three should be documented
122+
assert!(p.root().join("target/doc/foo/index.html").is_file());
123+
assert!(p.root().join("target/doc/bar/index.html").is_file());
124+
assert!(p.root().join("target/doc/baz/index.html").is_file());
125+
}
126+
127+
#[cargo_test(nightly, reason = "public-dependency feature is unstable")]
128+
fn doc_with_private_dependency() {
129+
// foo -> bar (private) -> baz
130+
// baz should NOT be documented (transitive private dep)
131+
132+
Package::new("baz", "0.0.1")
133+
.file("src/lib.rs", "pub fn baz() {}")
134+
.publish();
135+
136+
Package::new("bar", "0.0.1")
137+
.cargo_feature("public-dependency")
138+
.dep("baz", "0.0.1")
139+
.file("src/lib.rs", "extern crate baz; pub fn bar() {}")
140+
.publish();
141+
142+
let p = project()
143+
.file(
144+
"Cargo.toml",
145+
r#"
146+
cargo-features = ["public-dependency"]
147+
148+
[package]
149+
name = "foo"
150+
version = "0.0.1"
151+
edition = "2015"
152+
153+
[dependencies]
154+
bar = { version = "0.0.1", public = false }
155+
"#,
156+
)
157+
.file("src/lib.rs", "extern crate bar; pub fn foo() {}")
158+
.build();
159+
160+
p.cargo("doc -Zpublic-dependency")
161+
.masquerade_as_nightly_cargo(&["public-dependency"])
162+
.with_stderr_data(
163+
str![[r#"
164+
[UPDATING] `dummy-registry` index
165+
[LOCKING] 2 packages to latest compatible versions
166+
[DOWNLOADING] crates ...
167+
[DOWNLOADED] baz v0.0.1 (registry `dummy-registry`)
168+
[DOWNLOADED] bar v0.0.1 (registry `dummy-registry`)
169+
[DOCUMENTING] bar v0.0.1
170+
[CHECKING] baz v0.0.1
171+
[CHECKING] bar v0.0.1
172+
[DOCUMENTING] foo v0.0.1 ([ROOT]/foo)
173+
[FINISHED] `dev` profile [unoptimized + debuginfo] target(s) in [ELAPSED]s
174+
[GENERATED] [ROOT]/foo/target/doc/foo/index.html
175+
176+
"#]]
177+
.unordered(),
178+
)
179+
.run();
180+
181+
// Only foo and bar documented, not baz
182+
assert!(p.root().join("target/doc/foo/index.html").is_file());
183+
assert!(p.root().join("target/doc/bar/index.html").is_file());
184+
assert!(!p.root().join("target/doc/baz/index.html").is_file());
185+
}
186+
187+
#[cargo_test(nightly, reason = "public-dependency feature is unstable")]
188+
fn doc_mixed_public_private_deps() {
189+
// Mix of public and private deps
190+
Package::new("pub_dep", "0.0.1")
191+
.file("src/lib.rs", "pub fn pub_dep() {}")
192+
.publish();
193+
194+
Package::new("priv_dep", "0.0.1")
195+
.file("src/lib.rs", "pub fn priv_dep() {}")
196+
.publish();
197+
198+
Package::new("transitive", "0.0.1")
199+
.file("src/lib.rs", "pub fn transitive() {}")
200+
.publish();
201+
202+
Package::new("priv_dep_with_dep", "0.0.1")
203+
.dep("transitive", "0.0.1")
204+
.file("src/lib.rs", "extern crate transitive; pub fn priv_dep_with_dep() {}")
205+
.publish();
206+
207+
let p = project()
208+
.file(
209+
"Cargo.toml",
210+
r#"
211+
cargo-features = ["public-dependency"]
212+
213+
[package]
214+
name = "foo"
215+
version = "0.0.1"
216+
edition = "2015"
217+
218+
[dependencies]
219+
pub_dep = { version = "0.0.1", public = true }
220+
priv_dep = { version = "0.0.1", public = false }
221+
priv_dep_with_dep = "0.0.1"
222+
"#,
223+
)
224+
.file(
225+
"src/lib.rs",
226+
"extern crate pub_dep; extern crate priv_dep; extern crate priv_dep_with_dep; pub fn foo() {}",
227+
)
228+
.build();
229+
230+
p.cargo("doc -Zpublic-dependency")
231+
.masquerade_as_nightly_cargo(&["public-dependency"])
232+
.run();
233+
234+
// Direct deps documented, transitive private deps not documented
235+
assert!(p.root().join("target/doc/foo/index.html").is_file());
236+
assert!(p.root().join("target/doc/pub_dep/index.html").is_file());
237+
assert!(p.root().join("target/doc/priv_dep/index.html").is_file());
238+
assert!(p.root().join("target/doc/priv_dep_with_dep/index.html").is_file());
239+
240+
// transitive should NOT be documented
241+
assert!(!p.root().join("target/doc/transitive/index.html").is_file());
242+
}

‎tests/testsuite/main.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,7 @@ mod diagnostics;
9191
mod direct_minimal_versions;
9292
mod directory;
9393
mod doc;
94+
mod doc_direct_deps;
9495
mod docscrape;
9596
mod edition;
9697
mod error;

0 commit comments

Comments
 (0)