Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

clarify doc(cfg) wording #96059

Merged
merged 1 commit into from
Apr 16, 2022
Merged

clarify doc(cfg) wording #96059

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/doc/unstable-book/src/language-features/doc-cfg.md
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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;
}