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.
rust-lang · Apr 15, 2022 · 753d567 · 753d567
1 parent e7575f9
commit 753d567
Show file tree

Hide file tree

Showing 7 changed files with 43 additions and 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
@@ -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
@@ -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");
         }
@@ -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
@@ -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."
         );
     })
 }

diff --git 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
@@ -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
@@ -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 {
@@ -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 {
@@ -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();
@@ -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
@@ -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;
 }