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

View all comments

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 const _: () = ();. 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 https://github.com/rust-lang/rust/labels/T-rustdoc or open a topic in the #t-rustdoc Zulip channel.

Attributes to be documented:

• allow claimed by @kantnero:
  • #158070
  • #158244
• automatically_derived
• cfg_attr claimed by @kantnero here: #158664
• cfg claimed by @kantnero:
  • #158070
  • #158244
• cfi_encoding (unstable)
• cold claimed by @valentynkit here: https://github.com/rust-lang/rust/pull/158484
• collapse_debuginfo
• const_continue (unstable)
• coroutine (unstable)
• coverage
• crate_name
• crate_type
• debugger_visualizer
• deny claimed by @kantnero: #158244
• deprecated claimed by @kantnero: https://github.com/rust-lang/rust/pull/158244
• diagnostic::do_not_recommend claimed by @kantnero here
• diagnostic::on_const (unstable)
• diagnostic::on_move (unstable)
• diagnostic::on_type_error (unstable)
• diagnostic::on_unimplemented claimed by @kantnero here
• diagnostic::on_unknown (unstable)
• diagnostic::on_unmatched_args (unstable)
• doc claimed by @kantnero here
• expect claimed by @kantnero here: #158664
• export_name (unsafe (in Rust >=2024))
• export_stable (unstable)
• feature claimed by @kantnero here
• ffi_const (unstable, unsafe)
• ffi_pure (unstable, unsafe)
• forbid claimed by @kantnero: #158244
• force_target_feature
• fundamental (unstable)
• ignore claimed by @kantnero here
• inline claimed by @valentynkit here: #158348
• 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 https://github.com/rust-lang/rust/pull/157957
• naked (unsafe)
• no_builtins
• no_core (unstable)
• no_implicit_prelude
• no_link
• no_main
• no_mangle (unsafe (in Rust >=2024))
• no_std claimed by @jschillem here: https://github.com/rust-lang/rust/pull/158886
• non_exhaustive claimed by @Kristianerik here: https://github.com/rust-lang/rust/pull/159861
• optimize (unstable)
• panic_handler
• patchable_function_entry (unstable)
• path claimed by @kantnero here: #158664
• pin_v2 (unstable)
• proc_macro_attribute
• proc_macro_derive
• proc_macro claimed by @josetorrs here: https://github.com/rust-lang/rust/pull/158962
• recursion_limit
• reexport_test_harness_main (unstable)
• register_tool (unstable)
• repr
• sanitize
• should_panic claimed by @kantnero here: #158664
• splat (unstable)
• target_feature
• test_runner (unstable)
• thread_local (unstable)
• track_caller claimed by @valentynkit here: https://github.com/rust-lang/rust/pull/158484
• type_length_limit
• used claimed by @kantnero here: #158664
• warn: by @kantnero: https://github.com/rust-lang/rust/pull/158244
• windows_subsystem

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

Choose one unchecked, unclaimed attribute from the list and read PR #142472 to understand the #[doc(attribute = "…")] mechanism on const _: () = ();. Check the corresponding Rust Reference section and the existing libcore/libstd documentation patterns. Done means adding a beginner-friendly entry with a relative Reference link.