Tracking issue for documenting individual built-in inert attributes in the standard library using `#[doc(attribute = "…")]`

[fmease]

Back in August 2025 we merged PR #142472 which added a mechanism for us to document built-in inert attributes in libcore/libstd in the form of a new internal attribute #[doc(attribute = "…")] to be placed on dummy modules. So far though, 9 months later, we haven't actually started documenting any attributes.

Important

Similar to the preexisting "keyword docs" in the std library, these proposed "built-in attribute docs" are not meant to "replace" or "compete" with the Rust Reference!

Instead, they're merely meant to represent a guide-level explanation, not a reference-level one. They're to be written in more beginner-friendly language and they needn't exhaustively describe each attribute.

Finally, each "entry" ought to link to the relevant part of the Rust Reference if available using a relative filesystem path not a URL to allow for offline reading. Preferably at the bottom.

If there are any issues with #[doc(attribute = "…")] itself, please create a new issue labeled T-rustdoc Relevant to the rustdoc team, which will review and decide on the PR/issue. or open a topic in the #t-rustdoc Zulip channel.

---

Attributes to be documented:

• allow claimed by @kantnero: Add documentation for allow and cfg attributes. #158070
• automatically_derived
• cfg_attr
• cfg claimed by @kantnero: Add documentation for allow and cfg attributes. #158070
• cfi_encoding (unstable)
• cold
• collapse_debuginfo
• const_continue (unstable)
• coroutine (unstable)
• coverage
• crate_name
• crate_type
• debugger_visualizer
• deny claimed by @kantnero:
• deprecated
• diagnostic::do_not_recommend
• diagnostic::on_const (unstable)
• diagnostic::on_move (unstable)
• diagnostic::on_type_error (unstable)
• diagnostic::on_unimplemented
• diagnostic::on_unknown (unstable)
• diagnostic::on_unmatched_args (unstable)
• doc
• expect
• export_name (unsafe (in Rust >=2024))
• export_stable (unstable)
• feature
• ffi_const (unstable, unsafe)
• ffi_pure (unstable, unsafe)
• forbid claimed by @kantnero:
• force_target_feature
• fundamental (unstable)
• ignore
• inline
• instruction_set
• link_name
• link_ordinal
• link_section (unsafe (in Rust >=2024))
• link
• loop_match (unstable)
• macro_escape (deprecated: use macro_use)
• macro_export
• macro_use
• marker (unstable)
• may_dangle (unstable)
• move_size_limit
• must_not_suspend (unstable)
• must_use Add documentation for the must_use attribute #157957
• naked (unsafe)
• no_builtins
• no_core (unstable)
• no_implicit_prelude
• no_link
• no_main
• no_mangle (unsafe (in Rust >=2024))
• no_std
• non_exhaustive
• optimize (unstable)
• panic_handler
• patchable_function_entry (unstable)
• path
• pin_v2 (unstable)
• proc_macro_attribute
• proc_macro_derive
• proc_macro
• recursion_limit
• reexport_test_harness_main (unstable)
• register_tool (unstable)
• repr
• sanitize
• should_panic
• splat (unstable)
• stable (unstable)
• target_feature
• test_runner (unstable)
• thread_local (unstable)
• track_caller
• type_length_limit
• unstable (unstable)
• used
• warn
• windows_subsystem

This list intentionally does not include internal attributes.
Disclaimer: This list may contain errors and might be missing some attributes.

[fmease]

I don't actually know which team(s) are gonna be responsible for reviewing these PRs. Strictly speaking it should be T-lang-docs, right, but I don't think they have anything close to enough bandwidth. For keyword docs, it's actually T-libs & T-libs-contributors who approve these PRs in practice. T-compiler was recently asked to also review T-libs PRs, so that's also a group that can review these.

cc @GuillaumeGomez @rust-lang/lang-docs

[fmease]

Holding off on adding E-help-wanted Call for participation: Help is requested to fix this issue. until this tracking issue actually contains an exhaustive checklist of built-in inert attributes.

[traviscross]

I don't actually know which team(s) are gonna be responsible for reviewing these PRs. Strictly speaking it should be T-lang-docs, right, but...

Probably we (lang-docs) should take these, at least to start. We'll try to respin or hand off if we get behind. If the rate of these is low, as it has been for changes to the keyword docs (where I take assignment when I see them on nontrivial ones affecting stable features), it might be OK.

Revising attribute documentation on the Reference side has been one of our big projects, so it's on the mind, and we'll want to ensure some alignment.

[softfault]

I'd like to work on the first attribute documentation PR for #[must_use]. Would that be a good starting point for this tracking issue?

[GuillaumeGomez]

Sure, go ahead.