Attribute documentation for `used`, `expect`, `should_panic`, `cfg_attr`, and `path` by kantnero · Pull Request #158664 · rust-lang/rust

kantnero · 2026-07-01T15:44:53Z

Attribute documentation for used, expect, should_panic, cfg_attr, and path using the #[doc(attribute = "")] mechanism

Tested with: ./x test library/std --doc

r? @GuillaumeGomez
cc @traviscross @fmease

rustbot · 2026-07-01T15:45:36Z

r? @JohnTitor

rustbot has assigned @JohnTitor.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

Owners of files modified in this PR: @ChrisDenton, libs
@ChrisDenton, libs expanded to 13 candidates
Random selection from Darksonn, JohnTitor, Mark-Simulacrum, clarfonthey, jhpratt

GuillaumeGomez · 2026-07-02T12:55:47Z

+/// 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.


Suggested change

/// configuration predicate is true. If the condition is false, the attributes are ignored.

View changes since the review

GuillaumeGomez · 2026-07-02T12:57:28Z

+///
+/// ```rust
+/// // This function is annotated with `#[test]` only when testing is active.
+/// #[cfg_attr(test, test)]


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.

View changes since the review

GuillaumeGomez · 2026-07-02T12:58:39Z

+/// }
+/// ```
+///
+/// The predicate uses the same syntax as [`cfg`]. For complex conditions, you can combine


Does it link to the right cfg page?

View changes since the review

You still didn't answer this question. When you generate doc locally, what is the link of this item?

/rust/build/x86_64-unknown-linux-gnu/doc/core/attribute.cfg.html

I just checked it links to macro cfg

So it's not the right link.

Yes, I have removed it

GuillaumeGomez · 2026-07-02T12:59:28Z

+/// ```
+///
+/// The predicate uses the same syntax as [`cfg`]. For complex conditions, you can combine
+/// `all(...)`, `any(...)`, and `not(...)` just like with [`cfg`].


Add the same listing and example you added for cfg.

View changes since the review

GuillaumeGomez · 2026-07-02T12:59:58Z

+/// from optimizing them away even if they are not referenced anywhere else in the code.
+///
+/// It tells the compiler that an item is still in use or needed elsewhere and, because of this,
+/// it is kept in the output object.


"output object"?

View changes since the review

Ah ok I got it, so instead:

Suggested change

/// it is kept in the output object.

/// it is kept in the generated object files (files generated by `rustc` when compiling).

GuillaumeGomez · 2026-07-02T13:01:54Z

+//
+/// 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
+/// annotated with the test attribute.


Suggested change

/// annotated with the test attribute.

/// annotated with the `test` attribute.

View changes since the review

traviscross · 2026-07-10T09:23:40Z

+#[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


It just warns by default; it doesn't fail compilation.

View changes since the review

traviscross · 2026-07-10T09:27:53Z

+/// ```rust,compile_fail
+/// #[expect(unused_variables)]
+/// let name = "rust-lang";
+/// println!("{name}");
+/// ````


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.

View changes since the review

CI fails at this point that's the reason for the compile_fail

traviscross · 2026-07-10T09:29:30Z

+/// // The lint group is fulfilled as the variables are unused.
+/// #[expect(unused)]
+/// let x = 10;
+/// let y = 12;


The expect does not apply to let y = 12 here.

View changes since the review

traviscross · 2026-07-10T09:33:11Z

+/// println!("{name}");
+/// ````
+///
+/// In the example above the variable is used, so the `expect` is unfufilled this warning is emitted:


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:

View changes since the review

traviscross · 2026-07-10T09:33:46Z

+/// #[expect(unused_variables)]
+/// let name = "rust-lang";
+/// println!("{name}");
+/// ````


Suggested change

/// ````

/// ```

View changes since the review

traviscross · 2026-07-10T09:37:46Z

+/// 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`.


The behavior of this should probably be discussed; i.e., it doesn't cancel the expect.

View changes since the review

Yeah, this still warn on compilation I should probably remove that line.

#[expect(unused)] fn lang() { #[allow(unused)] let name = "rust-lang"; }

traviscross · 2026-07-10T09:38:47Z

+/// }
+/// ```
+///
+/// For complex conditions, you can combine `all(...)`, `any(...)`, and, `not(...)`.


Suggested change

/// For complex conditions, you can combine `all(...)`, `any(...)`, and, `not(...)`.

/// For complex conditions, you can combine `all(...)`, `any(...)`, and `not(...)`.

View changes since the review

traviscross · 2026-07-10T09:39:49Z

+/// ```rust
+/// #[cfg_attr(
+///     all(feature = "system", feature = "disk"),
+///     doc = "For module documentation, both `system`, and `disk` need to be enabled.",


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.",

View changes since the review

traviscross · 2026-07-10T09:41:06Z

+///
+/// For more information, see the Reference on [the `cfg_attr` attribute].
+///
+/// [the `cfg` attribute]: ../reference/conditional-compilation.html#the-cfg-attribute


Is this unused?

View changes since the review

traviscross · 2026-07-10T09:42:29Z

+
+#[doc(attribute = "ignore")]
+//
+/// The `ignore` attribute is used alongside the `test` attribute to prevent this test to be run by default.


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.

View changes since the review

kantnero · 2026-07-13T23:05:12Z

@rustbot ready

traviscross · 2026-07-14T22:52:28Z

@rustbot author

Not all review comments have been addressed, e.g., https://github.com/rust-lang/rust/pull/158664/changes#r3513255509, https://github.com/rust-lang/rust/pull/158664/changes#r3557842583, etc.

…h, and ignore Signed-off-by: Emmanuel Ugwu <emmanuelugwu121@gmail.com>

Signed-off-by: Emmanuel Ugwu <emmanuelugwu121@gmail.com>

rustbot · 2026-07-15T13:56:19Z

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.

rust-log-analyzer · 2026-07-15T14:02:56Z

The job tidy failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

fmt: checked 7024 files
tidy check
tidy [rustdoc_json (src)]: `rustdoc-json-types` modified, checking format version
tidy: Skipping binary file check, read-only filesystem
tidy [style (library)]: /checkout/library/core/src/attribute_docs.rs:669: unexplained "```ignore" doctest; try one:

* make the test actually pass, by adding necessary imports and declarations, or
* use "```text", if the code is not Rust code, or
* use "```compile_fail,Ennnn", if the code is expected to fail at compile time, or
* use "```should_panic", if the code is expected to fail at run time, or
* use "```no_run", if the code should type-check but not necessary linkable/runnable, or
* explain it like "```ignore (cannot-test-this-because-xxxx)", if the annotation cannot be avoided.


tidy [style (library)]: /checkout/library/core/src/attribute_docs.rs:675: unexplained "```ignore" doctest; try one:

* make the test actually pass, by adding necessary imports and declarations, or
* use "```text", if the code is not Rust code, or
* use "```compile_fail,Ennnn", if the code is expected to fail at compile time, or
* use "```should_panic", if the code is expected to fail at run time, or
* use "```no_run", if the code should type-check but not necessary linkable/runnable, or
* explain it like "```ignore (cannot-test-this-because-xxxx)", if the annotation cannot be avoided.


tidy [style (library)]: FAIL
removing old virtual environment
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'venv'
creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'virtualenv'
Requirement already satisfied: pip in ./build/venv/lib/python3.10/site-packages (26.1.2)
linting python files
---
Running eslint on rustdoc JS files
info: ES-Check: checking 7 files...
info: ✓ ES-Check passed! All files are ES10 compatible.
typechecking javascript files
tidy: The following check failed: style (library)
Command `/checkout/obj/build/x86_64-unknown-linux-gnu/stage1-tools-bin/rust-tidy --root-path=/checkout --cargo-path=/checkout/obj/build/x86_64-unknown-linux-gnu/stage0/bin/cargo --output-dir=/checkout/obj/build --concurrency=4 --npm-path=/node/bin/yarn --ci=true --extra-checks=py,cpp,js,spellcheck` failed with exit code 1
Created at: src/bootstrap/src/core/build_steps/tool.rs:1625:23
Executed at: src/bootstrap/src/core/build_steps/test.rs:1646:29

Command has failed. Rerun with -v to see more details.
Bootstrap failed while executing `test src/tools/tidy tidyselftest --extra-checks=py,cpp,js,spellcheck`
Currently active steps:
test::Tidy {  } at src/bootstrap/src/core/build_steps/test.rs:1568
Build completed unsuccessfully in 0:02:38
  local time: Wed Jul 15 14:02:46 UTC 2026

rustbot assigned JohnTitor Jul 1, 2026

rustbot added S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-libs Relevant to the library team, which will review and decide on the PR/issue. labels Jul 1, 2026

rustbot assigned GuillaumeGomez Jul 1, 2026

This comment has been minimized.

Sign in to view

rustbot added has-merge-commits PR has merge commits, merge with caution. S-waiting-on-author Status: This is awaiting some action (such as code changes or more information) from the author. labels Jul 1, 2026