Skip to content

Commit f1f2527

Browse files
Dylan-DPCDylan-DPC
authored
Rollup merge of rust-lang#96059 - euclio:doc-cfg, r=manishearth,guillaumegomez
clarify doc(cfg) wording The current "This is supported" wording implies that it's possible to still use the item on other configurations, but in an unsupported way. Changing this to "Available" removes this ambiguity.
2 parents fec05e8 + 753d567 commit f1f2527

File tree

7 files changed

+43
-54
lines changed

7 files changed

+43
-54
lines changed

‎src/doc/unstable-book/src/language-features/doc-cfg.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ The tracking issue for this feature is: [#43781]
77
The `doc_cfg` feature allows an API be documented as only available in some specific platforms.
88
This attribute has two effects:
99

10-
1. In the annotated item's documentation, there will be a message saying "This is supported on
10+
1. In the annotated item's documentation, there will be a message saying "Available on
1111
(platform) only".
1212

1313
2. The item's doc-tests will only run on the specific platform.

‎src/librustdoc/clean/cfg.rs

+3-6
Original file line numberDiff line numberDiff line change
@@ -171,11 +171,8 @@ impl Cfg {
171171
pub(crate) fn render_long_html(&self) -> String {
172172
let on = if self.should_use_with_in_description() { "with" } else { "on" };
173173

174-
let mut msg = format!(
175-
"This is supported {} <strong>{}</strong>",
176-
on,
177-
Display(self, Format::LongHtml)
178-
);
174+
let mut msg =
175+
format!("Available {on} <strong>{}</strong>", Display(self, Format::LongHtml));
179176
if self.should_append_only_to_description() {
180177
msg.push_str(" only");
181178
}
@@ -187,7 +184,7 @@ impl Cfg {
187184
pub(crate) fn render_long_plain(&self) -> String {
188185
let on = if self.should_use_with_in_description() { "with" } else { "on" };
189186

190-
let mut msg = format!("This is supported {} {}", on, Display(self, Format::LongPlain));
187+
let mut msg = format!("Available {on} {}", Display(self, Format::LongPlain));
191188
if self.should_append_only_to_description() {
192189
msg.push_str(" only");
193190
}

‎src/librustdoc/clean/cfg/tests.rs

+16-24
Original file line numberDiff line numberDiff line change
@@ -359,81 +359,73 @@ fn test_render_short_html() {
359359
#[test]
360360
fn test_render_long_html() {
361361
create_default_session_globals_then(|| {
362-
assert_eq!(
363-
word_cfg("unix").render_long_html(),
364-
"This is supported on <strong>Unix</strong> only."
365-
);
362+
assert_eq!(word_cfg("unix").render_long_html(), "Available on <strong>Unix</strong> only.");
366363
assert_eq!(
367364
name_value_cfg("target_os", "macos").render_long_html(),
368-
"This is supported on <strong>macOS</strong> only."
365+
"Available on <strong>macOS</strong> only."
369366
);
370367
assert_eq!(
371368
name_value_cfg("target_os", "wasi").render_long_html(),
372-
"This is supported on <strong>WASI</strong> only."
369+
"Available on <strong>WASI</strong> only."
373370
);
374371
assert_eq!(
375372
name_value_cfg("target_pointer_width", "16").render_long_html(),
376-
"This is supported on <strong>16-bit</strong> only."
373+
"Available on <strong>16-bit</strong> only."
377374
);
378375
assert_eq!(
379376
name_value_cfg("target_endian", "little").render_long_html(),
380-
"This is supported on <strong>little-endian</strong> only."
377+
"Available on <strong>little-endian</strong> only."
381378
);
382379
assert_eq!(
383380
(!word_cfg("windows")).render_long_html(),
384-
"This is supported on <strong>non-Windows</strong> only."
381+
"Available on <strong>non-Windows</strong> only."
385382
);
386383
assert_eq!(
387384
(word_cfg("unix") & word_cfg("windows")).render_long_html(),
388-
"This is supported on <strong>Unix and Windows</strong> only."
385+
"Available on <strong>Unix and Windows</strong> only."
389386
);
390387
assert_eq!(
391388
(word_cfg("unix") | word_cfg("windows")).render_long_html(),
392-
"This is supported on <strong>Unix or Windows</strong> only."
389+
"Available on <strong>Unix or Windows</strong> only."
393390
);
394391
assert_eq!(
395392
(word_cfg("unix") & word_cfg("windows") & word_cfg("debug_assertions"))
396393
.render_long_html(),
397-
"This is supported on <strong>Unix and Windows and debug-assertions enabled\
398-
</strong> only."
394+
"Available on <strong>Unix and Windows and debug-assertions enabled</strong> only."
399395
);
400396
assert_eq!(
401397
(word_cfg("unix") | word_cfg("windows") | word_cfg("debug_assertions"))
402398
.render_long_html(),
403-
"This is supported on <strong>Unix or Windows or debug-assertions enabled\
404-
</strong> only."
399+
"Available on <strong>Unix or Windows or debug-assertions enabled</strong> only."
405400
);
406401
assert_eq!(
407402
(!(word_cfg("unix") | word_cfg("windows") | word_cfg("debug_assertions")))
408403
.render_long_html(),
409-
"This is supported on <strong>neither Unix nor Windows nor debug-assertions \
410-
enabled</strong>."
404+
"Available on <strong>neither Unix nor Windows nor debug-assertions enabled</strong>."
411405
);
412406
assert_eq!(
413407
((word_cfg("unix") & name_value_cfg("target_arch", "x86_64"))
414408
| (word_cfg("windows") & name_value_cfg("target_pointer_width", "64")))
415409
.render_long_html(),
416-
"This is supported on <strong>Unix and x86-64, or Windows and 64-bit</strong> only."
410+
"Available on <strong>Unix and x86-64, or Windows and 64-bit</strong> only."
417411
);
418412
assert_eq!(
419413
(!(word_cfg("unix") & word_cfg("windows"))).render_long_html(),
420-
"This is supported on <strong>not (Unix and Windows)</strong>."
414+
"Available on <strong>not (Unix and Windows)</strong>."
421415
);
422416
assert_eq!(
423417
((word_cfg("debug_assertions") | word_cfg("windows")) & word_cfg("unix"))
424418
.render_long_html(),
425-
"This is supported on <strong>(debug-assertions enabled or Windows) and Unix\
426-
</strong> only."
419+
"Available on <strong>(debug-assertions enabled or Windows) and Unix</strong> only."
427420
);
428421
assert_eq!(
429422
name_value_cfg("target_feature", "sse2").render_long_html(),
430-
"This is supported with <strong>target feature <code>sse2</code></strong> only."
423+
"Available with <strong>target feature <code>sse2</code></strong> only."
431424
);
432425
assert_eq!(
433426
(name_value_cfg("target_arch", "x86_64") & name_value_cfg("target_feature", "sse2"))
434427
.render_long_html(),
435-
"This is supported on <strong>x86-64 and target feature \
436-
<code>sse2</code></strong> only."
428+
"Available on <strong>x86-64 and target feature <code>sse2</code></strong> only."
437429
);
438430
})
439431
}

‎src/test/rustdoc-gui/item-info-overflow.goml

+2-2
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ assert-property: (".item-info", {"scrollWidth": "890"})
88
// Just to be sure we're comparing the correct "item-info":
99
assert-text: (
1010
".item-info",
11-
"This is supported on Android or Linux or Emscripten or DragonFly BSD",
11+
"Available on Android or Linux or Emscripten or DragonFly BSD",
1212
STARTS_WITH,
1313
)
1414

@@ -23,6 +23,6 @@ assert-property: ("#impl-SimpleTrait .item-info", {"scrollWidth": "866"})
2323
// Just to be sure we're comparing the correct "item-info":
2424
assert-text: (
2525
"#impl-SimpleTrait .item-info",
26-
"This is supported on Android or Linux or Emscripten or DragonFly BSD",
26+
"Available on Android or Linux or Emscripten or DragonFly BSD",
2727
STARTS_WITH,
2828
)

‎src/test/rustdoc-gui/item-info-width.goml

+1-1
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,5 @@ goto: file://|DOC_PATH|/lib2/struct.Foo.html
44
size: (1100, 800)
55
// We check that ".item-info" is bigger than its content.
66
assert-css: (".item-info", {"width": "790px"})
7-
assert-css: (".item-info .stab", {"width": "340px"})
7+
assert-css: (".item-info .stab", {"width": "289px"})
88
assert-position: (".item-info .stab", {"x": 295})

‎src/test/rustdoc/doc-cfg.rs

+11-11
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,29 @@
44
// @has doc_cfg/struct.Portable.html
55
// @!has - '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' ''
66
// @has - '//*[@id="method.unix_and_arm_only_function"]' 'fn unix_and_arm_only_function()'
7-
// @has - '//*[@class="stab portability"]' 'This is supported on Unix and ARM only.'
7+
// @has - '//*[@class="stab portability"]' 'Available on Unix and ARM only.'
88
// @has - '//*[@id="method.wasi_and_wasm32_only_function"]' 'fn wasi_and_wasm32_only_function()'
9-
// @has - '//*[@class="stab portability"]' 'This is supported on WASI and WebAssembly only.'
9+
// @has - '//*[@class="stab portability"]' 'Available on WASI and WebAssembly only.'
1010
pub struct Portable;
1111

1212
// @has doc_cfg/unix_only/index.html \
1313
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
14-
// 'This is supported on Unix only.'
14+
// 'Available on Unix only.'
1515
// @matches - '//*[@class="item-left module-item"]//*[@class="stab portability"]' '\AARM\Z'
1616
// @count - '//*[@class="stab portability"]' 2
1717
#[doc(cfg(unix))]
1818
pub mod unix_only {
1919
// @has doc_cfg/unix_only/fn.unix_only_function.html \
2020
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
21-
// 'This is supported on Unix only.'
21+
// 'Available on Unix only.'
2222
// @count - '//*[@class="stab portability"]' 1
2323
pub fn unix_only_function() {
2424
content::should::be::irrelevant();
2525
}
2626

2727
// @has doc_cfg/unix_only/trait.ArmOnly.html \
2828
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
29-
// 'This is supported on Unix and ARM only.'
29+
// 'Available on Unix and ARM only.'
3030
// @count - '//*[@class="stab portability"]' 1
3131
#[doc(cfg(target_arch = "arm"))]
3232
pub trait ArmOnly {
@@ -41,22 +41,22 @@ pub mod unix_only {
4141

4242
// @has doc_cfg/wasi_only/index.html \
4343
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
44-
// 'This is supported on WASI only.'
44+
// 'Available on WASI only.'
4545
// @matches - '//*[@class="item-left module-item"]//*[@class="stab portability"]' '\AWebAssembly\Z'
4646
// @count - '//*[@class="stab portability"]' 2
4747
#[doc(cfg(target_os = "wasi"))]
4848
pub mod wasi_only {
4949
// @has doc_cfg/wasi_only/fn.wasi_only_function.html \
5050
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
51-
// 'This is supported on WASI only.'
51+
// 'Available on WASI only.'
5252
// @count - '//*[@class="stab portability"]' 1
5353
pub fn wasi_only_function() {
5454
content::should::be::irrelevant();
5555
}
5656

5757
// @has doc_cfg/wasi_only/trait.Wasm32Only.html \
5858
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
59-
// 'This is supported on WASI and WebAssembly only.'
59+
// 'Available on WASI and WebAssembly only.'
6060
// @count - '//*[@class="stab portability"]' 1
6161
#[doc(cfg(target_arch = "wasm32"))]
6262
pub trait Wasm32Only {
@@ -78,15 +78,15 @@ pub mod wasi_only {
7878

7979
// @has doc_cfg/fn.uses_target_feature.html
8080
// @has - '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
81-
// 'This is supported with target feature avx only.'
81+
// 'Available with target feature avx only.'
8282
#[target_feature(enable = "avx")]
8383
pub unsafe fn uses_target_feature() {
8484
content::should::be::irrelevant();
8585
}
8686

8787
// @has doc_cfg/fn.uses_cfg_target_feature.html
8888
// @has - '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
89-
// 'This is supported with target feature avx only.'
89+
// 'Available with target feature avx only.'
9090
#[doc(cfg(target_feature = "avx"))]
9191
pub fn uses_cfg_target_feature() {
9292
uses_target_feature();
@@ -95,7 +95,7 @@ pub fn uses_cfg_target_feature() {
9595
// multiple attributes should be allowed
9696
// @has doc_cfg/fn.multiple_attrs.html \
9797
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
98-
// 'This is supported on x and y and z only.'
98+
// 'Available on x and y and z only.'
9999
#[doc(cfg(x))]
100100
#[doc(cfg(y), cfg(z))]
101101
pub fn multiple_attrs() {}

‎src/test/rustdoc/duplicate-cfg.rs

+9-9
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33

44
// @has 'foo/index.html'
55
// @matches '-' '//*[@class="item-left module-item"]//*[@class="stab portability"]' '^sync$'
6-
// @has '-' '//*[@class="item-left module-item"]//*[@class="stab portability"]/@title' 'This is supported on crate feature `sync` only'
6+
// @has '-' '//*[@class="item-left module-item"]//*[@class="stab portability"]/@title' 'Available on crate feature `sync` only'
77

88
// @has 'foo/struct.Foo.html'
99
// @has '-' '//*[@class="stab portability"]' 'sync'
@@ -13,41 +13,41 @@
1313
pub struct Foo;
1414

1515
// @has 'foo/bar/index.html'
16-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate feature sync only.'
16+
// @has '-' '//*[@class="stab portability"]' 'Available on crate feature sync only.'
1717
#[doc(cfg(feature = "sync"))]
1818
pub mod bar {
1919
// @has 'foo/bar/struct.Bar.html'
20-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate feature sync only.'
20+
// @has '-' '//*[@class="stab portability"]' 'Available on crate feature sync only.'
2121
#[doc(cfg(feature = "sync"))]
2222
pub struct Bar;
2323
}
2424

2525
// @has 'foo/baz/index.html'
26-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate features sync and send only.'
26+
// @has '-' '//*[@class="stab portability"]' 'Available on crate features sync and send only.'
2727
#[doc(cfg(all(feature = "sync", feature = "send")))]
2828
pub mod baz {
2929
// @has 'foo/baz/struct.Baz.html'
30-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate features sync and send only.'
30+
// @has '-' '//*[@class="stab portability"]' 'Available on crate features sync and send only.'
3131
#[doc(cfg(feature = "sync"))]
3232
pub struct Baz;
3333
}
3434

3535
// @has 'foo/qux/index.html'
36-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate feature sync only.'
36+
// @has '-' '//*[@class="stab portability"]' 'Available on crate feature sync only.'
3737
#[doc(cfg(feature = "sync"))]
3838
pub mod qux {
3939
// @has 'foo/qux/struct.Qux.html'
40-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate features sync and send only.'
40+
// @has '-' '//*[@class="stab portability"]' 'Available on crate features sync and send only.'
4141
#[doc(cfg(all(feature = "sync", feature = "send")))]
4242
pub struct Qux;
4343
}
4444

4545
// @has 'foo/quux/index.html'
46-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate feature sync and crate feature send and foo only.'
46+
// @has '-' '//*[@class="stab portability"]' 'Available on crate feature sync and crate feature send and foo only.'
4747
#[doc(cfg(all(feature = "sync", feature = "send", foo)))]
4848
pub mod quux {
4949
// @has 'foo/quux/struct.Quux.html'
50-
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate feature sync and crate feature send and foo and bar only.'
50+
// @has '-' '//*[@class="stab portability"]' 'Available on crate feature sync and crate feature send and foo and bar only.'
5151
#[doc(cfg(all(feature = "send", feature = "sync", bar)))]
5252
pub struct Quux;
5353
}

0 commit comments

Comments
 (0)