mikros/rust
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Rollup merge of #130931 - GuillaumeGomez:standalone-crate, r=notriddle

Browse Source 
Rename `standalone` doctest attribute into `standalone_crate`

Following [zulip discussion](https://rust-lang.zulipchat.com/#narrow/stream/266220-t-rustdoc/topic/Renaming.20code.20block.20.22standalone.22.20attribute.3F) and poll results.

r? `@notriddle`
This commit is contained in:
Matthias Krüger 2024-09-29 16:51:55 +02:00 committed by GitHub
commit 3097951023
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
12 changed files with 165 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
library/core/src/panic/location.rs
View File

@ -44,7 +44,7 @@ impl<'a> Location<'a> {
///
/// # Examples
///
/// ```standalone
/// ```standalone_crate
/// use std::panic::Location;
///
/// /// Returns the [`Location`] at which it is called.

4
src/doc/rustdoc/src/write-documentation/documentation-tests.md
View File

@ -414,11 +414,11 @@ In some cases, doctests cannot be merged. For example, if you have:
The problem with this code is that, if you change any other doctests, it'll likely break when
runing `rustdoc --test`, making it tricky to maintain.
This is where the `standalone` attribute comes in: it tells `rustdoc` that a doctest
This is where the `standalone_crate` attribute comes in: it tells `rustdoc` that a doctest
should not be merged with the others. So the previous code should use it:
```rust
//! ```standalone
//! ```standalone_crate
//! let location = std::panic::Location::caller();
//! assert_eq!(location.line(), 4);
//! ```

2
src/librustdoc/doctest.rs
View File

@ -837,7 +837,7 @@ fn add_test(&mut self, scraped_test: ScrapedDocTest) {
let is_standalone = !doctest.can_be_merged
|| scraped_test.langstr.compile_fail
|| scraped_test.langstr.test_harness
|| scraped_test.langstr.standalone
|| scraped_test.langstr.standalone_crate
|| self.rustdoc_options.nocapture
|| self.rustdoc_options.test_args.iter().any(|arg| arg == "--show-output");
if is_standalone {

2
src/librustdoc/doctest/make.rs
View File

@ -48,7 +48,7 @@ pub(crate) fn new(
) -> Self {
let can_merge_doctests = can_merge_doctests
&& lang_str.is_some_and(|lang_str| {
!lang_str.compile_fail && !lang_str.test_harness && !lang_str.standalone
!lang_str.compile_fail && !lang_str.test_harness && !lang_str.standalone_crate
});
let SourceInfo { crate_attrs, maybe_crate_attrs, crates, everything_else } =

77
src/librustdoc/html/markdown.rs
View File

@ -871,7 +871,7 @@ pub(crate) struct LangString {
pub(crate) rust: bool,
pub(crate) test_harness: bool,
pub(crate) compile_fail: bool,
pub(crate) standalone: bool,
pub(crate) standalone_crate: bool,
pub(crate) error_codes: Vec<String>,
pub(crate) edition: Option<Edition>,
pub(crate) added_classes: Vec<String>,
@ -1194,7 +1194,7 @@ fn default() -> Self {
rust: true,
test_harness: false,
compile_fail: false,
standalone: false,
standalone_crate: false,
error_codes: Vec::new(),
edition: None,
added_classes: Vec::new(),
@ -1264,8 +1264,8 @@ fn parse(
seen_rust_tags = !seen_other_tags || seen_rust_tags;
data.no_run = true;
}
LangStringToken::LangToken("standalone") => {
data.standalone = true;
LangStringToken::LangToken("standalone_crate") => {
data.standalone_crate = true;
seen_rust_tags = !seen_other_tags || seen_rust_tags;
}
LangStringToken::LangToken(x) if x.starts_with("edition") => {
@ -1298,44 +1298,47 @@ fn parse(
}
LangStringToken::LangToken(x) if extra.is_some() => {
let s = x.to_lowercase();
if let Some((flag, help)) = if s == "compile-fail"
|| s == "compile_fail"
|| s == "compilefail"
{
Some((
"compile_fail",
"the code block will either not be tested if not marked as a rust one \
or won't fail if it compiles successfully",
))
} else if s == "should-panic" || s == "should_panic" || s == "shouldpanic" {
Some((
"should_panic",
"the code block will either not be tested if not marked as a rust one \
or won't fail if it doesn't panic when running",
))
} else if s == "no-run" || s == "no_run" || s == "norun" {
Some((
"no_run",
"the code block will either not be tested if not marked as a rust one \
or will be run (which you might not want)",
))
} else if s == "test-harness" || s == "test_harness" || s == "testharness" {
Some((
"test_harness",
"the code block will either not be tested if not marked as a rust one \
or the code will be wrapped inside a main function",
))
} else {
None
if let Some(help) = match s.as_str() {
"compile-fail" | "compile_fail" | "compilefail" => Some(
"use `compile_fail` to invert the results of this test, so that it \
passes if it cannot be compiled and fails if it can",
),
"should-panic" | "should_panic" | "shouldpanic" => Some(
"use `should_panic` to invert the results of this test, so that if \
passes if it panics and fails if it does not",
),
"no-run" | "no_run" | "norun" => Some(
"use `no_run` to compile, but not run, the code sample during \
testing",
),
"test-harness" | "test_harness" | "testharness" => Some(
"use `test_harness` to run functions marked `#[test]` instead of a \
potentially-implicit `main` function",
),
"standalone" | "standalone_crate" | "standalone-crate" => {
if let Some(extra) = extra
&& extra.sp.at_least_rust_2024()
{
Some(
"use `standalone_crate` to compile this code block \
separately",
)
} else {
None
}
}
_ => None,
} {
if let Some(extra) = extra {
extra.error_invalid_codeblock_attr_with_help(
format!("unknown attribute `{x}`"),
|lint| {
lint.help(format!(
"there is an attribute with a similar name: `{flag}`"
))
.help(help);
lint.help(help).help(
"this code block may be skipped during testing, \
because unknown attributes are treated as markers for \
code samples written in other programming languages, \
unless it is also explicitly marked as `rust`",
);
},
);
}

4
tests/run-make/doctests-merge/doctest-standalone.rs
View File

@ -1,11 +1,11 @@
#![crate_name = "foo"]
#![crate_type = "lib"]
//! ```standalone
//! ```standalone_crate
//! foo::init();
//! ```
/// ```standalone
/// ```standalone_crate
/// foo::init();
/// ```
pub fn init() {

48
tests/rustdoc-ui/doctest/check-attr-test.stderr
View File

@ -8,8 +8,8 @@ error: unknown attribute `compile-fail`
9 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `compile_fail`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
= help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
note: the lint level is defined here
--> $DIR/check-attr-test.rs:3:9
|
@ -26,8 +26,8 @@ error: unknown attribute `compilefail`
9 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `compile_fail`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
= help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `comPile_fail`
--> $DIR/check-attr-test.rs:5:1
@ -39,8 +39,8 @@ error: unknown attribute `comPile_fail`
9 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `compile_fail`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
= help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `should-panic`
--> $DIR/check-attr-test.rs:12:1
@ -52,8 +52,8 @@ error: unknown attribute `should-panic`
16 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `should_panic`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `shouldpanic`
--> $DIR/check-attr-test.rs:12:1
@ -65,8 +65,8 @@ error: unknown attribute `shouldpanic`
16 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `should_panic`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `shOuld_panic`
--> $DIR/check-attr-test.rs:12:1
@ -78,8 +78,8 @@ error: unknown attribute `shOuld_panic`
16 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `should_panic`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `no-run`
--> $DIR/check-attr-test.rs:19:1
@ -91,8 +91,8 @@ error: unknown attribute `no-run`
23 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `no_run`
= help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
= help: use `no_run` to compile, but not run, the code sample during testing
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `norun`
--> $DIR/check-attr-test.rs:19:1
@ -104,8 +104,8 @@ error: unknown attribute `norun`
23 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `no_run`
= help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
= help: use `no_run` to compile, but not run, the code sample during testing
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `nO_run`
--> $DIR/check-attr-test.rs:19:1
@ -117,8 +117,8 @@ error: unknown attribute `nO_run`
23 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `no_run`
= help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
= help: use `no_run` to compile, but not run, the code sample during testing
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `test-harness`
--> $DIR/check-attr-test.rs:26:1
@ -130,8 +130,8 @@ error: unknown attribute `test-harness`
30 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `testharness`
--> $DIR/check-attr-test.rs:26:1
@ -143,8 +143,8 @@ error: unknown attribute `testharness`
30 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `tesT_harness`
--> $DIR/check-attr-test.rs:26:1
@ -156,8 +156,8 @@ error: unknown attribute `tesT_harness`
30 | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: aborting due to 12 previous errors

16
tests/rustdoc-ui/doctest/standalone-warning-2024.rs Normal file
View File

@ -0,0 +1,16 @@
// This test checks that it will output warnings for usage of `standalone` or `standalone_crate`.
//@ compile-flags:--test -Zunstable-options --edition 2024
//@ normalize-stdout-test: "tests/rustdoc-ui/doctest" -> "$$DIR"
//@ normalize-stdout-test: "finished in \d+\.\d+s" -> "finished in $$TIME"
//@ normalize-stdout-test: ".rs:\d+:\d+" -> ".rs:$$LINE:$$COL"
#![deny(warnings)]
//! ```standalone
//! bla
//! ```
//!
//! ```standalone-crate
//! bla
//! ```

38
tests/rustdoc-ui/doctest/standalone-warning-2024.stderr Normal file
View File

@ -0,0 +1,38 @@
error: unknown attribute `standalone`
--> $DIR/standalone-warning-2024.rs:10:1
|
10 | / //! ```standalone
11 | | //! bla
12 | | //! ```
13 | | //!
14 | | //! ```standalone-crate
15 | | //! bla
16 | | //! ```
| |_______^
|
= help: use `standalone_crate` to compile this code block separately
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
note: the lint level is defined here
--> $DIR/standalone-warning-2024.rs:8:9
|
8 | #![deny(warnings)]
| ^^^^^^^^
= note: `#[deny(rustdoc::invalid_codeblock_attributes)]` implied by `#[deny(warnings)]`
error: unknown attribute `standalone-crate`
--> $DIR/standalone-warning-2024.rs:10:1
|
10 | / //! ```standalone
11 | | //! bla
12 | | //! ```
13 | | //!
14 | | //! ```standalone-crate
15 | | //! bla
16 | | //! ```
| |_______^
|
= help: use `standalone_crate` to compile this code block separately
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: aborting due to 2 previous errors

10
tests/rustdoc-ui/doctest/standalone-warning.rs Normal file
View File

@ -0,0 +1,10 @@
// This test checks that it will not output warning for usage of `standalone` or `standalone_crate`.
//@ check-pass
//! ```standalone
//! bla
//! ```
//!
//! ```standalone-crate
//! bla
//! ```

52
tests/rustdoc-ui/lints/check-attr.stderr
View File

@ -10,8 +10,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `compile_fail`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
= help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
note: the lint level is defined here
--> $DIR/check-attr.rs:1:9
|
@ -30,8 +30,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `compile_fail`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
= help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `comPile_fail`
--> $DIR/check-attr.rs:3:1
@ -45,8 +45,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `compile_fail`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it compiles successfully
= help: use `compile_fail` to invert the results of this test, so that it passes if it cannot be compiled and fails if it can
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `should-panic`
--> $DIR/check-attr.rs:13:1
@ -60,8 +60,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `should_panic`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `shouldpanic`
--> $DIR/check-attr.rs:13:1
@ -75,8 +75,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `should_panic`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `sHould_panic`
--> $DIR/check-attr.rs:13:1
@ -90,8 +90,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `should_panic`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `no-run`
--> $DIR/check-attr.rs:23:1
@ -105,8 +105,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `no_run`
= help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
= help: use `no_run` to compile, but not run, the code sample during testing
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `norun`
--> $DIR/check-attr.rs:23:1
@ -120,8 +120,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `no_run`
= help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
= help: use `no_run` to compile, but not run, the code sample during testing
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `no_Run`
--> $DIR/check-attr.rs:23:1
@ -135,8 +135,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `no_run`
= help: the code block will either not be tested if not marked as a rust one or will be run (which you might not want)
= help: use `no_run` to compile, but not run, the code sample during testing
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `test-harness`
--> $DIR/check-attr.rs:33:1
@ -150,8 +150,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `testharness`
--> $DIR/check-attr.rs:33:1
@ -165,8 +165,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `teSt_harness`
--> $DIR/check-attr.rs:33:1
@ -180,8 +180,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: unknown attribute `rust2018`
--> $DIR/check-attr.rs:43:1
@ -222,8 +222,8 @@ LL | | /// boo
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `should_panic`
= help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
= help: use `should_panic` to invert the results of this test, so that if passes if it panics and fails if it does not
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: aborting due to 15 previous errors

8
tests/rustdoc-ui/lints/check-fail.stderr
View File

@ -31,8 +31,8 @@ LL | | //! let x = 12;
LL | | //! ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
note: the lint level is defined here
--> $DIR/check-fail.rs:6:9
|
@ -51,8 +51,8 @@ LL | | /// let x = 12;
LL | | /// ```
| |_______^
|
= help: there is an attribute with a similar name: `test_harness`
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
= help: use `test_harness` to run functions marked `#[test]` instead of a potentially-implicit `main` function
= help: this code block may be skipped during testing, because unknown attributes are treated as markers for code samples written in other programming languages, unless it is also explicitly marked as `rust`
error: aborting due to 4 previous errors