From 753d567989e9cd8f6b1a2b707c231d70838b7819 Mon Sep 17 00:00:00 2001 From: Andy Russell Date: Thu, 14 Apr 2022 19:03:56 -0400 Subject: [PATCH] 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. --- .../src/language-features/doc-cfg.md | 2 +- src/librustdoc/clean/cfg.rs | 9 ++--- src/librustdoc/clean/cfg/tests.rs | 40 ++++++++----------- src/test/rustdoc-gui/item-info-overflow.goml | 4 +- src/test/rustdoc-gui/item-info-width.goml | 2 +- src/test/rustdoc/doc-cfg.rs | 22 +++++----- src/test/rustdoc/duplicate-cfg.rs | 18 ++++----- 7 files changed, 43 insertions(+), 54 deletions(-) diff --git a/src/doc/unstable-book/src/language-features/doc-cfg.md b/src/doc/unstable-book/src/language-features/doc-cfg.md index e75f1aea992..b15f5ee66ab 100644 --- a/src/doc/unstable-book/src/language-features/doc-cfg.md +++ b/src/doc/unstable-book/src/language-features/doc-cfg.md @@ -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. diff --git a/src/librustdoc/clean/cfg.rs b/src/librustdoc/clean/cfg.rs index b72d2624177..0d213a5a2de 100644 --- a/src/librustdoc/clean/cfg.rs +++ b/src/librustdoc/clean/cfg.rs @@ -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 {} {}", - on, - Display(self, Format::LongHtml) - ); + let mut msg = + format!("Available {on} {}", Display(self, Format::LongHtml)); if self.should_append_only_to_description() { msg.push_str(" only"); } @@ -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"); } diff --git a/src/librustdoc/clean/cfg/tests.rs b/src/librustdoc/clean/cfg/tests.rs index 275d1b3ebd9..ece3fcb18b6 100644 --- a/src/librustdoc/clean/cfg/tests.rs +++ b/src/librustdoc/clean/cfg/tests.rs @@ -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 Unix only." - ); + assert_eq!(word_cfg("unix").render_long_html(), "Available on Unix only."); assert_eq!( name_value_cfg("target_os", "macos").render_long_html(), - "This is supported on macOS only." + "Available on macOS only." ); assert_eq!( name_value_cfg("target_os", "wasi").render_long_html(), - "This is supported on WASI only." + "Available on WASI only." ); assert_eq!( name_value_cfg("target_pointer_width", "16").render_long_html(), - "This is supported on 16-bit only." + "Available on 16-bit only." ); assert_eq!( name_value_cfg("target_endian", "little").render_long_html(), - "This is supported on little-endian only." + "Available on little-endian only." ); assert_eq!( (!word_cfg("windows")).render_long_html(), - "This is supported on non-Windows only." + "Available on non-Windows only." ); assert_eq!( (word_cfg("unix") & word_cfg("windows")).render_long_html(), - "This is supported on Unix and Windows only." + "Available on Unix and Windows only." ); assert_eq!( (word_cfg("unix") | word_cfg("windows")).render_long_html(), - "This is supported on Unix or Windows only." + "Available on Unix or Windows only." ); assert_eq!( (word_cfg("unix") & word_cfg("windows") & word_cfg("debug_assertions")) .render_long_html(), - "This is supported on Unix and Windows and debug-assertions enabled\ - only." + "Available on Unix and Windows and debug-assertions enabled only." ); assert_eq!( (word_cfg("unix") | word_cfg("windows") | word_cfg("debug_assertions")) .render_long_html(), - "This is supported on Unix or Windows or debug-assertions enabled\ - only." + "Available on Unix or Windows or debug-assertions enabled only." ); assert_eq!( (!(word_cfg("unix") | word_cfg("windows") | word_cfg("debug_assertions"))) .render_long_html(), - "This is supported on neither Unix nor Windows nor debug-assertions \ - enabled." + "Available on neither Unix nor Windows nor debug-assertions enabled." ); 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 Unix and x86-64, or Windows and 64-bit only." + "Available on Unix and x86-64, or Windows and 64-bit only." ); assert_eq!( (!(word_cfg("unix") & word_cfg("windows"))).render_long_html(), - "This is supported on not (Unix and Windows)." + "Available on not (Unix and Windows)." ); assert_eq!( ((word_cfg("debug_assertions") | word_cfg("windows")) & word_cfg("unix")) .render_long_html(), - "This is supported on (debug-assertions enabled or Windows) and Unix\ - only." + "Available on (debug-assertions enabled or Windows) and Unix only." ); assert_eq!( name_value_cfg("target_feature", "sse2").render_long_html(), - "This is supported with target feature sse2 only." + "Available with target feature sse2 only." ); assert_eq!( (name_value_cfg("target_arch", "x86_64") & name_value_cfg("target_feature", "sse2")) .render_long_html(), - "This is supported on x86-64 and target feature \ - sse2 only." + "Available on x86-64 and target feature sse2 only." ); }) } diff --git a/src/test/rustdoc-gui/item-info-overflow.goml b/src/test/rustdoc-gui/item-info-overflow.goml index 4ff719bfb7d..d6385e2acb8 100644 --- a/src/test/rustdoc-gui/item-info-overflow.goml +++ b/src/test/rustdoc-gui/item-info-overflow.goml @@ -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, ) @@ -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, ) diff --git a/src/test/rustdoc-gui/item-info-width.goml b/src/test/rustdoc-gui/item-info-width.goml index 7a32d902910..8b6d355a8f1 100644 --- a/src/test/rustdoc-gui/item-info-width.goml +++ b/src/test/rustdoc-gui/item-info-width.goml @@ -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}) diff --git a/src/test/rustdoc/doc-cfg.rs b/src/test/rustdoc/doc-cfg.rs index 9465c8a35c8..4cddb0b76d4 100644 --- a/src/test/rustdoc/doc-cfg.rs +++ b/src/test/rustdoc/doc-cfg.rs @@ -4,21 +4,21 @@ // @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(); @@ -26,7 +26,7 @@ pub mod unix_only { // @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 { @@ -41,14 +41,14 @@ 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(); @@ -56,7 +56,7 @@ pub mod wasi_only { // @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 { @@ -78,7 +78,7 @@ 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(); @@ -86,7 +86,7 @@ pub unsafe fn uses_target_feature() { // @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(); @@ -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() {} diff --git a/src/test/rustdoc/duplicate-cfg.rs b/src/test/rustdoc/duplicate-cfg.rs index 886ec675030..18f3900b263 100644 --- a/src/test/rustdoc/duplicate-cfg.rs +++ b/src/test/rustdoc/duplicate-cfg.rs @@ -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' @@ -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; }