Repository navigation
Tracking issue for documenting individual built-in inert attributes in the standard library using #[doc(attribute = "…")] #157604
Description
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
Attributes to be documented:
-
allowclaimed by @kantnero: -
automatically_derived: addautomatically_derivedattribute documentation #163390 -
cfg_attrclaimed by @kantnero here: -
cfgclaimed by @kantnero: -
cfi_encoding(unstable) -
coldclaimed by @valentynkit here: Add documentation for thecoldandtrack_callerattributes #158484 -
collapse_debuginfo -
const_continue(unstable) -
coroutine(unstable) -
coverage -
crate_name: Add documentation for thecrate_nameattribute #163434 -
crate_type: Add Documentation for thecrate_typeattribute #164519 -
debugger_visualizer -
denyclaimed by @kantnero: -
deprecatedclaimed by @kantnero: Attribute docsdeprecated,warn,allow,cfg,deny, andforbid#158244 -
diagnostic::do_not_recommendclaimed by @kantnero here -
diagnostic::on_const(unstable) -
diagnostic::on_move(unstable) -
diagnostic::on_type_error(unstable) -
diagnostic::on_unimplementedclaimed by @kantnero here -
diagnostic::on_unknown(unstable) -
diagnostic::on_unmatched_args(unstable) -
docclaimed by @kantnero here -
expectclaimed by @kantnero here: Attribute documentation forused,expect,should_panic,cfg_attr, andpath#158664 -
export_name(unsafe (in Rust >=2024)): Document symbol name attributes #159758 -
export_stable(unstable) -
featureclaimed by @kantnero here -
ffi_const(unstable, unsafe) -
ffi_pure(unstable, unsafe) -
forbidclaimed by @kantnero: -
force_target_feature -
fundamental(unstable) -
ignoreclaimed by @kantnero here -
inlineclaimed by @valentynkit here: Add documentation for theinlineattribute #158348 -
instruction_set -
link_name: Document symbol name attributes #159758 -
link_ordinal -
link_section(unsafe (in Rust >=2024)): Document the link_section attribute #159734 -
link -
loop_match(unstable) -
macro_escape(deprecated: usemacro_use) -
macro_export -
macro_use -
marker(unstable) -
may_dangle(unstable) -
move_size_limit -
must_not_suspend(unstable) -
must_use: Add documentation for themust_useattribute #157957 -
naked(unsafe) -
no_builtins -
no_core(unstable) -
no_implicit_prelude -
no_link -
no_main: Add documentation for theno_mainandreprattributes #163627 -
no_mangle(unsafe (in Rust >=2024)): Document symbol name attributes #159758 -
no_stdclaimed by @jschillem here: Add documentation for theno_stdattribute #158886 -
non_exhaustiveclaimed by @Kristianerik here: Add documentation for thenon_exhaustiveattribute #159861 -
optimize(unstable) -
panic_handler -
patchable_function_entry(unstable) -
pathclaimed by @kantnero here: Attribute documentation forused,expect,should_panic,cfg_attr, andpath#158664 -
pin_v2(unstable) -
proc_macro_attribute -
proc_macro_derive -
proc_macroclaimed by @josetorrs here: Addproc_macroattribute documentation #158962 -
recursion_limit: Document therecursion_limitbuilt-in attribute #162369 -
reexport_test_harness_main(unstable) -
register_tool(unstable) -
repr: Add documentation for theno_mainandreprattributes #163627 -
sanitize -
should_panicclaimed by @kantnero here: Attribute documentation forused,expect,should_panic,cfg_attr, andpath#158664 -
splat(unstable) -
target_feature: Add documentation for thetarget_featureattribute #160218 -
test_runner(unstable) -
thread_local(unstable) -
track_callerclaimed by @valentynkit here: Add documentation for thecoldandtrack_callerattributes #158484 -
type_length_limit -
usedclaimed by @kantnero here: Attribute documentation forused,expect,should_panic,cfg_attr, andpath#158664 -
warn: by @kantnero: Attribute docsdeprecated,warn,allow,cfg,deny, andforbid#158244 -
windows_subsystem: Addwindows_subsystemattribute documentation #164189
This list intentionally does not include internal attributes.
Disclaimer: This list may contain errors and might be missing some attributes.
Activity
fmease commentedon Jun 8, 2026
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 commentedon Jun 8, 2026
Holding off on adding E-help-wantedCall for participation: Help is requested to fix this issue.
until this tracking issue actually contains an exhaustive checklist of built-in inert attributes.
[-]Tracking issue for documenting individual built-in attributes in the standard library using `#[doc(attribute = "…")]`[/-][+]Tracking issue for documenting individual built-in inert attributes in the standard library using `#[doc(attribute = "…")]`[/+]traviscross commentedon Jun 8, 2026
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 commentedon Jun 15, 2026
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 commentedon Jun 15, 2026
Sure, go ahead.
mejrs commentedon Jun 16, 2026
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 commentedon Jun 16, 2026
Well, using the same attribute in some rustc internal crate should do the trick. Otherwise in the rustc dev guide?
traviscross commentedon Jun 16, 2026
There is https://doc.rust-lang.org/nightly/nightly-rustc/index.html. Maybe it'd fit somewhere there.
86 remaining items
Rollup merge of rust-lang#163627 - literally-user:docs-repr-no_main_a…
Unrolled build for #163627 in rollup 163754
Rollup merge of rust-lang#163434 - krokodeyu:document-crate-name-attr…
Unrolled build for #163434 in rollup 164072
kiana1kaslana commentedon Oct 11, 2026
I'd like to claim
windows_subsystem.krokodeyu commentedon Oct 18, 2026
I'd like to claim
crate_type.Rollup merge of rust-lang#164189 - kiana1kaslana:docs-windows-subsyst…
Unrolled build for #164189 in rollup 164556
Rollup merge of rust-lang#162369 - kiana1kaslana:doc-recursion-limit-…
Rollup merge of rust-lang#162369 - kiana1kaslana:doc-recursion-limit-…
Rollup merge of rust-lang#162369 - kiana1kaslana:doc-recursion-limit-…
Unrolled build for #162369 in rollup 164699
Rollup merge of rust-lang#164519 - krokodeyu:document-crate-type-attr…
Unrolled build for #164519 in rollup 165659