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 <emmanuelugwu121@gmail.com>
…h, and ignore Signed-off-by: Emmanuel Ugwu <emmanuelugwu121@gmail.com>
Signed-off-by: Emmanuel Ugwu <emmanuelugwu121@gmail.com>
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
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 <emmanuelugwu121@gmail.com>
rustbot
added
S-waiting-on-review
Signed-off-by: Emmanuel Ugwu <emmanuelugwu121@gmail.com>
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 <emmanuelugwu121@gmail.com>
Signed-off-by: Emmanuel Ugwu <emmanuelugwu121@gmail.com>
| /// | ||
| /// * `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 <emmanuelugwu121@gmail.com>
Contributor
Author
|
@rustbot ready |
Contributor
|
☔ The latest upstream changes (presumably #159046) made this pull request unmergeable. Please resolve the merge conflicts by rebasing. |
traviscross
reviewed
Jul 10, 2026
| #[doc(attribute = "expect")] | ||
| // | ||
| /// The `#[expect]` attribute declares that a particular lint is expected to be emitted. | ||
| /// It is an equivalent of the `allow` attribute, except that it will fail compilation if the `expect`ed lint |
Contributor
There was a problem hiding this comment.
It just warns by default; it doesn't fail compilation.
Comment on lines
+465
to
+469
| /// ```rust,compile_fail | ||
| /// #[expect(unused_variables)] | ||
| /// let name = "rust-lang"; | ||
| /// println!("{name}"); | ||
| /// ```` |
Contributor
There was a problem hiding this comment.
The rendering of compile_fail to the reader will be misleading since this only fails due to the harness defaults. Maybe it's worth adding an explicit #[deny(unfulfilled_lint_expectations)] so this will make sense to the reader.
Comment on lines
+502
to
+505
| /// // The lint group is fulfilled as the variables are unused. | ||
| /// #[expect(unused)] | ||
| /// let x = 10; | ||
| /// let y = 12; |
Contributor
There was a problem hiding this comment.
The expect does not apply to let y = 12 here.
| /// println!("{name}"); | ||
| /// ```` | ||
| /// | ||
| /// In the example above the variable is used, so the `expect` is unfufilled this warning is emitted: |
Contributor
There was a problem hiding this comment.
Suggested change
| /// In the example above the variable is used, so the `expect` is unfufilled this warning is emitted: | |
| /// In the example above the variable is used, so the `expect` is unfulfilled this warning is emitted: |
| /// #[expect(unused_variables)] | ||
| /// let name = "rust-lang"; | ||
| /// println!("{name}"); | ||
| /// ```` |
Contributor
There was a problem hiding this comment.
Suggested change
| /// ```` | |
| /// ``` |
| /// It is an equivalent of the `allow` attribute, except that it will fail compilation if the `expect`ed lint | ||
| /// wasn't emitted. | ||
| /// | ||
| /// `expect` can be overridden by `warn`, `allow`, `deny`, and `forbid`. |
Contributor
There was a problem hiding this comment.
The behavior of this should probably be discussed; i.e., it doesn't cancel the expect.
| /// } | ||
| /// ``` | ||
| /// | ||
| /// For complex conditions, you can combine `all(...)`, `any(...)`, and, `not(...)`. |
Contributor
There was a problem hiding this comment.
Suggested change
| /// For complex conditions, you can combine `all(...)`, `any(...)`, and, `not(...)`. | |
| /// For complex conditions, you can combine `all(...)`, `any(...)`, and `not(...)`. |
| /// ```rust | ||
| /// #[cfg_attr( | ||
| /// all(feature = "system", feature = "disk"), | ||
| /// doc = "For module documentation, both `system`, and `disk` need to be enabled.", |
Contributor
There was a problem hiding this comment.
Suggested change
| /// doc = "For module documentation, both `system`, and `disk` need to be enabled.", | |
| /// doc = "For module documentation, both `system` and `disk` need to be enabled.", |
| /// | ||
| /// For more information, see the Reference on [the `cfg_attr` attribute]. | ||
| /// | ||
| /// [the `cfg` attribute]: ../reference/conditional-compilation.html#the-cfg-attribute |
Contributor
There was a problem hiding this comment.
Is this unused?
|
|
||
| #[doc(attribute = "ignore")] | ||
| // | ||
| /// The `ignore` attribute is used alongside the `test` attribute to prevent this test to be run by default. |
Contributor
There was a problem hiding this comment.
Suggested change
| /// The `ignore` attribute is used alongside the `test` attribute to prevent this test to be run by default. | |
| /// The `ignore` attribute is used alongside the `test` attribute to prevent this test from being run by default. |
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
6 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