Skip to content

Commit

Permalink
clarify doc(cfg) wording
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
euclio committed Apr 15, 2022
1 parent e7575f9 commit 753d567
Show file tree
Hide file tree
Showing 7 changed files with 43 additions and 54 deletions.
2 changes: 1 addition & 1 deletion src/doc/unstable-book/src/language-features/doc-cfg.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ The tracking issue for this feature is: [#43781]
The `doc_cfg` feature allows an API be documented as only available in some specific platforms.
This attribute has two effects:

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

2. The item's doc-tests will only run on the specific platform.
Expand Down
9 changes: 3 additions & 6 deletions src/librustdoc/clean/cfg.rs
Original file line number Diff line number Diff line change
Expand Up @@ -171,11 +171,8 @@ impl Cfg {
pub(crate) fn render_long_html(&self) -> String {
let on = if self.should_use_with_in_description() { "with" } else { "on" };

let mut msg = format!(
"This is supported {} <strong>{}</strong>",
on,
Display(self, Format::LongHtml)
);
let mut msg =
format!("Available {on} <strong>{}</strong>", Display(self, Format::LongHtml));
if self.should_append_only_to_description() {
msg.push_str(" only");
}
Expand All @@ -187,7 +184,7 @@ impl Cfg {
pub(crate) fn render_long_plain(&self) -> String {
let on = if self.should_use_with_in_description() { "with" } else { "on" };

let mut msg = format!("This is supported {} {}", on, Display(self, Format::LongPlain));
let mut msg = format!("Available {on} {}", Display(self, Format::LongPlain));
if self.should_append_only_to_description() {
msg.push_str(" only");
}
Expand Down
40 changes: 16 additions & 24 deletions src/librustdoc/clean/cfg/tests.rs
Original file line number Diff line number Diff line change
Expand Up @@ -359,81 +359,73 @@ fn test_render_short_html() {
#[test]
fn test_render_long_html() {
create_default_session_globals_then(|| {
assert_eq!(
word_cfg("unix").render_long_html(),
"This is supported on <strong>Unix</strong> only."
);
assert_eq!(word_cfg("unix").render_long_html(), "Available on <strong>Unix</strong> only.");
assert_eq!(
name_value_cfg("target_os", "macos").render_long_html(),
"This is supported on <strong>macOS</strong> only."
"Available on <strong>macOS</strong> only."
);
assert_eq!(
name_value_cfg("target_os", "wasi").render_long_html(),
"This is supported on <strong>WASI</strong> only."
"Available on <strong>WASI</strong> only."
);
assert_eq!(
name_value_cfg("target_pointer_width", "16").render_long_html(),
"This is supported on <strong>16-bit</strong> only."
"Available on <strong>16-bit</strong> only."
);
assert_eq!(
name_value_cfg("target_endian", "little").render_long_html(),
"This is supported on <strong>little-endian</strong> only."
"Available on <strong>little-endian</strong> only."
);
assert_eq!(
(!word_cfg("windows")).render_long_html(),
"This is supported on <strong>non-Windows</strong> only."
"Available on <strong>non-Windows</strong> only."
);
assert_eq!(
(word_cfg("unix") & word_cfg("windows")).render_long_html(),
"This is supported on <strong>Unix and Windows</strong> only."
"Available on <strong>Unix and Windows</strong> only."
);
assert_eq!(
(word_cfg("unix") | word_cfg("windows")).render_long_html(),
"This is supported on <strong>Unix or Windows</strong> only."
"Available on <strong>Unix or Windows</strong> only."
);
assert_eq!(
(word_cfg("unix") & word_cfg("windows") & word_cfg("debug_assertions"))
.render_long_html(),
"This is supported on <strong>Unix and Windows and debug-assertions enabled\
</strong> only."
"Available on <strong>Unix and Windows and debug-assertions enabled</strong> only."
);
assert_eq!(
(word_cfg("unix") | word_cfg("windows") | word_cfg("debug_assertions"))
.render_long_html(),
"This is supported on <strong>Unix or Windows or debug-assertions enabled\
</strong> only."
"Available on <strong>Unix or Windows or debug-assertions enabled</strong> only."
);
assert_eq!(
(!(word_cfg("unix") | word_cfg("windows") | word_cfg("debug_assertions")))
.render_long_html(),
"This is supported on <strong>neither Unix nor Windows nor debug-assertions \
enabled</strong>."
"Available on <strong>neither Unix nor Windows nor debug-assertions enabled</strong>."
);
assert_eq!(
((word_cfg("unix") & name_value_cfg("target_arch", "x86_64"))
| (word_cfg("windows") & name_value_cfg("target_pointer_width", "64")))
.render_long_html(),
"This is supported on <strong>Unix and x86-64, or Windows and 64-bit</strong> only."
"Available on <strong>Unix and x86-64, or Windows and 64-bit</strong> only."
);
assert_eq!(
(!(word_cfg("unix") & word_cfg("windows"))).render_long_html(),
"This is supported on <strong>not (Unix and Windows)</strong>."
"Available on <strong>not (Unix and Windows)</strong>."
);
assert_eq!(
((word_cfg("debug_assertions") | word_cfg("windows")) & word_cfg("unix"))
.render_long_html(),
"This is supported on <strong>(debug-assertions enabled or Windows) and Unix\
</strong> only."
"Available on <strong>(debug-assertions enabled or Windows) and Unix</strong> only."
);
assert_eq!(
name_value_cfg("target_feature", "sse2").render_long_html(),
"This is supported with <strong>target feature <code>sse2</code></strong> only."
"Available with <strong>target feature <code>sse2</code></strong> only."
);
assert_eq!(
(name_value_cfg("target_arch", "x86_64") & name_value_cfg("target_feature", "sse2"))
.render_long_html(),
"This is supported on <strong>x86-64 and target feature \
<code>sse2</code></strong> only."
"Available on <strong>x86-64 and target feature <code>sse2</code></strong> only."
);
})
}
Expand Down
4 changes: 2 additions & 2 deletions src/test/rustdoc-gui/item-info-overflow.goml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ assert-property: (".item-info", {"scrollWidth": "890"})
// Just to be sure we're comparing the correct "item-info":
assert-text: (
".item-info",
"This is supported on Android or Linux or Emscripten or DragonFly BSD",
"Available on Android or Linux or Emscripten or DragonFly BSD",
STARTS_WITH,
)

Expand All @@ -23,6 +23,6 @@ assert-property: ("#impl-SimpleTrait .item-info", {"scrollWidth": "866"})
// Just to be sure we're comparing the correct "item-info":
assert-text: (
"#impl-SimpleTrait .item-info",
"This is supported on Android or Linux or Emscripten or DragonFly BSD",
"Available on Android or Linux or Emscripten or DragonFly BSD",
STARTS_WITH,
)
2 changes: 1 addition & 1 deletion src/test/rustdoc-gui/item-info-width.goml
Original file line number Diff line number Diff line change
Expand Up @@ -4,5 +4,5 @@ goto: file://|DOC_PATH|/lib2/struct.Foo.html
size: (1100, 800)
// We check that ".item-info" is bigger than its content.
assert-css: (".item-info", {"width": "790px"})
assert-css: (".item-info .stab", {"width": "340px"})
assert-css: (".item-info .stab", {"width": "289px"})
assert-position: (".item-info .stab", {"x": 295})
22 changes: 11 additions & 11 deletions src/test/rustdoc/doc-cfg.rs
Original file line number Diff line number Diff line change
Expand Up @@ -4,29 +4,29 @@
// @has doc_cfg/struct.Portable.html
// @!has - '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' ''
// @has - '//*[@id="method.unix_and_arm_only_function"]' 'fn unix_and_arm_only_function()'
// @has - '//*[@class="stab portability"]' 'This is supported on Unix and ARM only.'
// @has - '//*[@class="stab portability"]' 'Available on Unix and ARM only.'
// @has - '//*[@id="method.wasi_and_wasm32_only_function"]' 'fn wasi_and_wasm32_only_function()'
// @has - '//*[@class="stab portability"]' 'This is supported on WASI and WebAssembly only.'
// @has - '//*[@class="stab portability"]' 'Available on WASI and WebAssembly only.'
pub struct Portable;

// @has doc_cfg/unix_only/index.html \
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on Unix only.'
// 'Available on Unix only.'
// @matches - '//*[@class="item-left module-item"]//*[@class="stab portability"]' '\AARM\Z'
// @count - '//*[@class="stab portability"]' 2
#[doc(cfg(unix))]
pub mod unix_only {
// @has doc_cfg/unix_only/fn.unix_only_function.html \
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on Unix only.'
// 'Available on Unix only.'
// @count - '//*[@class="stab portability"]' 1
pub fn unix_only_function() {
content::should::be::irrelevant();
}

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

// @has doc_cfg/wasi_only/index.html \
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on WASI only.'
// 'Available on WASI only.'
// @matches - '//*[@class="item-left module-item"]//*[@class="stab portability"]' '\AWebAssembly\Z'
// @count - '//*[@class="stab portability"]' 2
#[doc(cfg(target_os = "wasi"))]
pub mod wasi_only {
// @has doc_cfg/wasi_only/fn.wasi_only_function.html \
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on WASI only.'
// 'Available on WASI only.'
// @count - '//*[@class="stab portability"]' 1
pub fn wasi_only_function() {
content::should::be::irrelevant();
}

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

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

// @has doc_cfg/fn.uses_cfg_target_feature.html
// @has - '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported with target feature avx only.'
// 'Available with target feature avx only.'
#[doc(cfg(target_feature = "avx"))]
pub fn uses_cfg_target_feature() {
uses_target_feature();
Expand All @@ -95,7 +95,7 @@ pub fn uses_cfg_target_feature() {
// multiple attributes should be allowed
// @has doc_cfg/fn.multiple_attrs.html \
// '//*[@id="main-content"]/*[@class="item-info"]/*[@class="stab portability"]' \
// 'This is supported on x and y and z only.'
// 'Available on x and y and z only.'
#[doc(cfg(x))]
#[doc(cfg(y), cfg(z))]
pub fn multiple_attrs() {}
18 changes: 9 additions & 9 deletions src/test/rustdoc/duplicate-cfg.rs
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@

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

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

// @has 'foo/bar/index.html'
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate feature sync only.'
// @has '-' '//*[@class="stab portability"]' 'Available on crate feature sync only.'
#[doc(cfg(feature = "sync"))]
pub mod bar {
// @has 'foo/bar/struct.Bar.html'
// @has '-' '//*[@class="stab portability"]' 'This is supported on crate feature sync only.'
// @has '-' '//*[@class="stab portability"]' 'Available on crate feature sync only.'
#[doc(cfg(feature = "sync"))]
pub struct Bar;
}

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

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

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

0 comments on commit 753d567

Please sign in to comment.