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

[fmease]

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 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
  • Attribute docs deprecated , warn, allow, cfg, deny, and forbid  #158244
• automatically_derived
• cfg_attr claimed by @kantnero here: Attribute documentation for used, expect, should_panic, cfg_attr, and path #158664
• cfg claimed by @kantnero:
  • Add documentation for allow and cfg attributes. #158070
  • Attribute docs deprecated , warn, allow, cfg, deny, and forbid  #158244
• cfi_encoding (unstable)
• cold claimed by @valentynkit here: Add documentation for the cold and track_caller attributes #158484
• collapse_debuginfo
• const_continue (unstable)
• coroutine (unstable)
• coverage
• crate_name
• crate_type
• debugger_visualizer
• deny claimed by @kantnero: Attribute docs deprecated , warn, allow, cfg, deny, and forbid  #158244
• deprecated claimed by @kantnero: Attribute docs deprecated , warn, allow, cfg, deny, and forbid  #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: Attribute documentation for used, expect, should_panic, cfg_attr, and path #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: Attribute docs deprecated , warn, allow, cfg, deny, and forbid  #158244
• force_target_feature
• fundamental (unstable)
• ignore claimed by @kantnero here
• inline claimed by @valentynkit here: Add documentation for the inline attribute #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 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 claimed by @jschillem here: Add documentation for the no_std attribute #158886
• non_exhaustive claimed by @Kristianerik here: Add documentation for the non_exhaustive attribute #159861
• optimize (unstable)
• panic_handler
• patchable_function_entry (unstable)
• path claimed by @kantnero here: Attribute documentation for used, expect, should_panic, cfg_attr, and path #158664
• pin_v2 (unstable)
• proc_macro_attribute
• proc_macro_derive
• proc_macro claimed by @josetorrs here: Add proc_macro attribute documentation #158962
• recursion_limit
• reexport_test_harness_main (unstable)
• register_tool (unstable)
• repr
• sanitize
• should_panic claimed by @kantnero here: Attribute documentation for used, expect, should_panic, cfg_attr, and path #158664
• splat (unstable)
• target_feature
• test_runner (unstable)
• thread_local (unstable)
• track_caller claimed by @valentynkit here: Add documentation for the cold and track_caller attributes #158484
• type_length_limit
• used claimed by @kantnero here: Attribute documentation for used, expect, should_panic, cfg_attr, and path #158664
• warn: by @kantnero: Attribute docs deprecated , warn, allow, cfg, deny, and forbid  #158244
• 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.

[mejrs]

This list intentionally does not include internal attributes.

It would be nice to have a place where these are documented. That wouldn't be in the std crate docs, obviously. But I do sometimes struggle with using internal attributes and even minimal docs would be helpful.. Is there a place in the rustc workspace where this fits?

[GuillaumeGomez]

Well, using the same attribute in some rustc internal crate should do the trick. Otherwise in the rustc dev guide?

[traviscross]

There is https://doc.rust-lang.org/nightly/nightly-rustc/index.html. Maybe it'd fit somewhere there.