Attribute documentation for used, expect, should_panic, cfg_attr, and path#158664
Open
kantnero wants to merge 16 commits into
Open
Attribute documentation for used, expect, should_panic, cfg_attr, and path#158664kantnero wants to merge 16 commits into
used, expect, should_panic, cfg_attr, and path#158664kantnero wants to merge 16 commits into
Conversation
rustbot
added
S-waiting-on-review
Collaborator
|
r? @JohnTitor rustbot has assigned @JohnTitor. Use Why was this reviewer chosen?The reviewer was selected based on:
|
Collaborator
|
This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed. Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers. |
This comment has been minimized.
This comment has been minimized.
rustbot
added
has-merge-commits
…h, and ignore Signed-off-by: Emmanuel Ugwu <[email protected]>
…h, and ignore Signed-off-by: Emmanuel Ugwu <[email protected]>
Signed-off-by: Emmanuel Ugwu <[email protected]>
rustbot
removed
S-waiting-on-author
80 tasks
| /// Used for conditional application of attributes. | ||
| /// | ||
| /// The `cfg_attr` attribute applies one or more attributes to an item only if a given | ||
| /// configuration predicate is true. If the condition is false, the attributes are ignored. |
Member
There was a problem hiding this comment.
Suggested change
| /// configuration predicate is true. If the condition is false, the attributes are ignored. |
| /// | ||
| /// ```rust | ||
| /// // This function is annotated with `#[test]` only when testing is active. | ||
| /// #[cfg_attr(test, test)] |
Member
There was a problem hiding this comment.
It's neat, but I think it's a bit too complex (test is present twice). I suggest instead to make it a test only on linux for example. Like that we have a clear predicate, completely different than the applied attribute.
| /// } | ||
| /// ``` | ||
| /// | ||
| /// The predicate uses the same syntax as [`cfg`]. For complex conditions, you can combine |
Member
There was a problem hiding this comment.
Does it link to the right cfg page?
Member
There was a problem hiding this comment.
You still didn't answer this question. When you generate doc locally, what is the link of this item?
Contributor
Author
There was a problem hiding this comment.
/rust/build/x86_64-unknown-linux-gnu/doc/core/attribute.cfg.html
Contributor
Author
There was a problem hiding this comment.
I just checked it links to macro cfg
Member
There was a problem hiding this comment.
So it's not the right link.
Contributor
Author
There was a problem hiding this comment.
Yes, I have removed it
Comment on lines
+403
to
+404
| /// To confirm, we compile this program into an object file, you'll see that `FOO` makes it to the | ||
| /// object file but `BAR` doesn't. Neither static variable is used by the program. |
Member
There was a problem hiding this comment.
Suggested change
| /// To confirm, we compile this program into an object file, you'll see that `FOO` makes it to the | |
| /// object file but `BAR` doesn't. Neither static variable is used by the program. | |
| /// To confirm, we compile this code and then we confirm that `FOO` is present in the generated files, but not `BAR`. |
Comment on lines
+426
to
+427
| /// The `ignore` attribute is used with the `test` attribute to stop the test harness from | ||
| /// executing a function as a test. The `ignore` attribute may only be applied to functions |
Member
There was a problem hiding this comment.
Suggested change
| /// The `ignore` attribute is used with the `test` attribute to stop the test harness from | |
| /// executing a function as a test. The `ignore` attribute may only be applied to functions | |
| /// The `ignore` attribute is used alongside the `test` attribute to prevent this test to be run by default. The `ignore` attribute may only be applied to functions |
Comment on lines
+487
to
+488
| /// Multiple lints can be set to `expect` at once, each one is expected separately. For a lint group, it’s enough | ||
| /// if one lint inside the group has been emitted: |
Member
There was a problem hiding this comment.
Suggested change
| /// Multiple lints can be set to `expect` at once, each one is expected separately. For a lint group, it’s enough | |
| /// if one lint inside the group has been emitted: | |
| /// Multiple lints can be set to `expect` at once, each one is expected separately. |
Comment on lines
+549
to
+563
| /// running 1 test | ||
| /// test test_without_panic - should panic ... FAILED | ||
| /// | ||
| /// failures: | ||
| /// | ||
| /// ---- test_without_panic stdout ---- | ||
| /// A test that does not panic | ||
| /// note: test did not panic as expected at src/main.rs:3:4 | ||
| /// | ||
| /// failures: | ||
| /// test_without_panic | ||
| /// | ||
| /// test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s | ||
| /// | ||
| /// error: test failed, to rerun pass `--bin panic` |
Member
There was a problem hiding this comment.
Suggested change
| /// running 1 test | |
| /// test test_without_panic - should panic ... FAILED | |
| /// | |
| /// failures: | |
| /// | |
| /// ---- test_without_panic stdout ---- | |
| /// A test that does not panic | |
| /// note: test did not panic as expected at src/main.rs:3:4 | |
| /// | |
| /// failures: | |
| /// test_without_panic | |
| /// | |
| /// test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s | |
| /// | |
| /// error: test failed, to rerun pass `--bin panic` | |
| /// test test_without_panic - should panic ... FAILED |
GuillaumeGomez
requested changes
Jul 6, 2026
rustbot
added
S-waiting-on-author
Collaborator
|
Reminder, once the PR becomes ready for a review, use |
Signed-off-by: Emmanuel Ugwu <[email protected]>
rustbot
added
S-waiting-on-review
Signed-off-by: Emmanuel Ugwu <[email protected]>
Comment on lines
+196
to
+198
| /// Used for conditional application of attributes. | ||
| /// | ||
| /// The `cfg_attr` attribute is used to conditionally apply one or more attributes to an item. |
Member
There was a problem hiding this comment.
Suggested change
| /// Used for conditional application of attributes. | |
| /// | |
| /// The `cfg_attr` attribute is used to conditionally apply one or more attributes to an item. | |
| /// The `cfg_attr` attribute is used to conditionally apply one or more attributes to an item. |
| /// Example: | ||
| /// | ||
| /// ```rust | ||
| /// // This function is annotated with `#[test]` only when on Linux platform. |
Member
There was a problem hiding this comment.
Suggested change
| /// // This function is annotated with `#[test]` only when on Linux platform. | |
| /// // This function is annotated with `#[test]` only on Linux platforms. |
| /// | ||
| /// ```rust | ||
| /// #[cfg_attr(all(feature = "system", feature = "disk"), | ||
| /// doc = "This module is only accessible when both `system` and `disk` are enabled")] |
Member
There was a problem hiding this comment.
The doc message is wrong considering that there is no cfg in here.
Comment on lines
+388
to
+389
| /// The `#[used]` attribute can be used on static variables to prevent the Rust compiler | ||
| /// from optimizing them away even if they are not referenced anywhere else in the code. |
Member
There was a problem hiding this comment.
Suggested change
| /// The `#[used]` attribute can be used on static variables to prevent the Rust compiler | |
| /// from optimizing them away even if they are not referenced anywhere else in the code. | |
| /// The `#[used]` attribute can be used on static variables to prevent the Rust compiler | |
| /// from optimizing them away even if they are not used anywhere in the current crate. |
| /// #[test] | ||
| /// #[ignore] | ||
| /// fn test() { | ||
| /// // ... This test is ignored by the test harness (the compiler still compiles it). |
Member
There was a problem hiding this comment.
Suggested change
| /// // ... This test is ignored by the test harness (the compiler still compiles it). | |
| /// // ... This test is ignored by the test harness (the compiler still compiles it). |
Signed-off-by: Emmanuel Ugwu <[email protected]>
Signed-off-by: Emmanuel Ugwu <[email protected]>
| /// | ||
| /// * `all`: True if all given predicates are true. | ||
| /// * `any`: True if at least one of the given predicates is true. | ||
| /// * `not`: True if the predicate is false and false if the predicate is true. |
Member
There was a problem hiding this comment.
Suggested change
| /// * `not`: True if the predicate is false and false if the predicate is true. | |
| /// * `not`: True if the predicate is false. |
Comment on lines
+226
to
+227
| /// #[cfg_attr(all(feature = "system", feature = "disk"), | ||
| /// doc = "For module documentation, both `system`, and `disk` need to be enabled.")] |
Member
There was a problem hiding this comment.
Suggested change
| /// #[cfg_attr(all(feature = "system", feature = "disk"), | |
| /// doc = "For module documentation, both `system`, and `disk` need to be enabled.")] | |
| /// #[cfg_attr( | |
| /// all(feature = "system", feature = "disk"), | |
| /// doc = "For module documentation, both `system`, and `disk` need to be enabled.", | |
| /// )] |
| #[doc(attribute = "used")] | ||
| // | ||
| /// The `#[used]` attribute can be used on static variables to prevent the Rust compiler | ||
| /// from optimizing them away even if they are not used anywhere in the current crate. |
Member
There was a problem hiding this comment.
Suggested change
| /// from optimizing them away even if they are not used anywhere in the current crate. | |
| /// from optimizing them away even if they are not used in the current crate. |
| /// from optimizing them away even if they are not used anywhere in the current crate. | ||
| /// | ||
| /// It tells the compiler that an item is still in use or needed elsewhere and, because of this, | ||
| /// it is kept in the files generated by `rustc` when compiling. |
Member
There was a problem hiding this comment.
Suggested change
| /// it is kept in the files generated by `rustc` when compiling. | |
| /// should be kept in the files generated by `rustc` when compiling. |
|
|
||
| #[doc(attribute = "should_panic")] | ||
| // | ||
| /// The `should_panic` attribute is used with the `test` attribute to indicate that a test is expected |
Member
There was a problem hiding this comment.
Suggested change
| /// The `should_panic` attribute is used with the `test` attribute to indicate that a test is expected | |
| /// The `should_panic` attribute is used alongside the `test` attribute to indicate that a test is expected |
| /// The `should_panic` attribute is used with the `test` attribute to indicate that a test is expected | ||
| /// to panic and will fail if it doesn't. | ||
| /// | ||
| /// The `should_panic` attribute may only be applied to functions annotated with the test attribute. |
Member
There was a problem hiding this comment.
Suggested change
| /// The `should_panic` attribute may only be applied to functions annotated with the test attribute. | |
| /// The `should_panic` attribute may only be applied to functions annotated with the `test` attribute. |
Comment on lines
+572
to
+584
| /// You can combine `#[path]` with `#[cfg]` Or even better: use `#[cfg_attr]` to load platform-specific files: | ||
| /// | ||
| /// ```rust,compile_fail | ||
| /// // On Linux, the platform/linux.rs source file is loaded. | ||
| /// #[cfg(target_os = "linux")] | ||
| /// #[path = "platform/linux.rs"] | ||
| /// mod platform; | ||
| /// | ||
| /// // On Windows, the platform/windows.rs source file is loaded. | ||
| /// #[cfg(target_os = "windows")] | ||
| /// #[path = "platform/windows.rs"] | ||
| /// mod platform; | ||
| /// ``` |
Member
There was a problem hiding this comment.
This whole part is actually not really useful as it doesn't provide information useful for the path attribute. Please remove it.
| // | ||
| /// The `#[path = "..."]` attribute tells the compiler where to find a module's source file, overriding the default | ||
| /// file lookup. | ||
| /// |
Member
There was a problem hiding this comment.
You need to add an explanation to how the path works (does it need to be absolute? If not, from where is it relative, etc).
Signed-off-by: Emmanuel Ugwu <[email protected]>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
View all comments
Attribute documentation for
used,expect,should_panic,cfg_attr, andpathusing the#[doc(attribute = "")]mechanismTested with: ./x test library/std --doc
r? @GuillaumeGomez
cc @traviscross @fmease