document some rustc_dump attributes

compiler/rustc_attr_ir/src/attribute_docs.rs

@@ -0,0 +1,225 @@
+macro_rules! include_example {
+    ($name:literal) => {
+        concat!(
+            "```rust,compile_fail\n",
+            include_str!(concat!("../../../tests/ui/attributes/doc_examples/", $name, ".rs")),
+            "```\n",
+            "produces:\n",
+            " ```text\n",
+            include_str!(concat!("../../../tests/ui/attributes/doc_examples/", $name, ".stderr")),
+            "```\n",
+        )
+    };
+}
+
+#[cfg_attr(not(bootstrap), doc(attribute = "rustc_dump_clauses"))]
+/// Dumps the list of [`ty::Clause`]s as computed by the [`clauses_of`] query.
+///
+/// See [`AttributeKind::RustcDumpClauses`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_clauses")]
+///
+/// # Example: super trait bounds are not elaborated
+///
+#[doc = include_example!("rustc_dump_clauses_super_trait")]
+///
+/// [`clauses_of`]: ../rustc_middle/ty/struct.TyCtxt.html#method.clauses_of
+/// [`ty::Clause`]: ../rustc_middle/ty/struct.Clause.html
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_def_parents")]
+/// Dumps the parents of the annotated item and of any anonymous constants contained within it.
+///
+/// See also [`opt_parent`](../rustc_middle/ty/struct.TyCtxt.html#method.opt_parent).
+///
+/// See [`AttributeKind::RustcDumpDefParents`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_def_parents")]
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_def_path")]
+/// Dumps the def path of the annotated item.
+///
+/// See also [`def_path_str`] and [`def_path_str_with_args`].
+///
+/// See [`AttributeKind::RustcDumpDefPath`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_def_path")]
+///
+/// [`def_path_str`]: ../rustc_middle/ty/struct.TyCtxt.html#method.def_path_str
+/// [`def_path_str_with_args`]: ../rustc_middle/ty/struct.TyCtxt.html#method.def_path_str_with_args
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_generics")]
+/// Dumps the generics of the annotated item.
+///
+/// See [`generics_of`] and [`ty::Generics`] for what "generics" means here.
+///
+/// See [`AttributeKind::RustcDumpGenerics`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_generics")]
+///
+/// [`generics_of`]: ../rustc_middle/ty/struct.TyCtxt.html#method.generics_of
+/// [`ty::Generics`]: ../rustc_middle/ty/struct.Generics.html
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_hidden_type_of_opaques")]
+/// Dumps the hidden types of the opaque items in this crate.
+///
+/// This ends up calling the [`type_of`] query, which, for opaque types, reveals their hidden types.
+///
+/// See [`AttributeKind::RustcDumpHiddenTypeOfOpaques`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_hidden_type_of_opaques")]
+///
+/// [`type_of`]: ../rustc_middle/ty/struct.TyCtxt.html#method.type_of
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_inferred_outlives")]
+/// Dumps the inferred outlives-clauses of the annotated item.
+///
+/// See also the [`inferred_outlives_of`] query.
+///
+/// See [`AttributeKind::RustcDumpInferredOutlives`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_inferred_outlives")]
+///
+/// [`inferred_outlives_of`]: ../rustc_middle/ty/struct.TyCtxt.html#method.inferred_outlives_of
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_item_bounds")]
+/// Dumps the item bounds of the annotated item.
+///
+/// This ends up calling the [`item_bounds`] query and prints the [`ty::Clause`] of the item.
+///
+/// See [`AttributeKind::RustcDumpItemBounds`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_item_bounds")]
+///
+/// [`item_bounds`]: ../rustc_middle/ty/struct.TyCtxt.html#method.item_bounds
+/// [`ty::Clause`]: ../rustc_middle/ty/struct.Clause.html
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_layout")]
+/// Dumps the layout of the annotated item.
+///
+/// This ends up calling the [`layout_of`] query to get the [`Layout`] of the annotated item. If used
+/// with the `debug` modifier, it will print the entirety of `Layout`. Other modifiers will print
+/// only parts of it.
+///
+/// See [`AttributeKind::RustcDumpLayout`] for the internal representation of this attribute.
+///
+/// # Example: `debug`
+///
+#[doc = include_example!("rustc_dump_layout_debug")]
+///
+/// # Example: `largest_niche`
+///
+#[doc = include_example!("rustc_dump_layout_largest_niche")]
+///
+/// # Example: `size`
+///
+#[doc = include_example!("rustc_dump_layout_size")]
+///
+/// # Example: `align`
+///
+#[doc = include_example!("rustc_dump_layout_align")]
+///
+/// # Example: `backend_repr`
+///
+#[doc = include_example!("rustc_dump_layout_backend_repr")]
+///
+/// # Example: `homogeneous_aggregate`
+///
+#[doc = include_example!("rustc_dump_layout_homogeneous_aggregate")]
+///
+/// [`layout_of`]: ../rustc_middle/ty/struct.TyCtxt.html#method.layout_of
+/// [`Layout`]: rustc_abi::Layout
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_object_lifetime_defaults")]
+/// Dumps the trait object lifetime defaults induced by the type parameters of the annotated item.
+///
+/// It will dump this information separately for each type parameter of the annotated item.
+///
+/// See also the [`object_lifetime_default`] query.
+///
+/// See [`AttributeKind::RustcDumpObjectLifetimeDefaults`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_object_lifetime_defaults")]
+///
+/// [`object_lifetime_default`]: ../rustc_middle/ty/struct.TyCtxt.html#method.object_lifetime_default
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_symbol_name")]
+/// Dumps the symbol name of the annotated item, also demangling it if necessary.
+///
+/// See also the [`symbol_name`] query.
+///
+/// See [`AttributeKind::RustcDumpSymbolName`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_symbol_name")]
+///
+/// [`symbol_name`]: ../rustc_middle/ty/struct.TyCtxt.html#method.symbol_name
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_variances")]
+/// Dumps the variances of the annotated item.
+///
+/// See also the [`variances_of`] query and [`ty::Variance`].
+///
+/// See [`AttributeKind::RustcDumpVariances`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_variances")]
+///
+/// [`variances_of`]: ../rustc_middle/ty/struct.TyCtxt.html#method.variances_of
+/// [`ty::Variance`]: ../rustc_middle/ty/enum.Variance.html
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_variances_of_opaques")]
+/// Dumps the variances of opaque types in this crate.
+///
+/// See also the [`variances_of`] query.
+///
+/// See [`AttributeKind::RustcDumpVariancesOfOpaques`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_variances_of_opaques")]
+///
+/// [`variances_of`]: ../rustc_middle/ty/struct.TyCtxt.html#method.variances_of
+const _: () = ();
+
+#[doc(attribute = "rustc_dump_vtable")]
+/// Dumps the virtual method table ("vtable") of the annotated item.
+///
+/// See also the [`vtable_entries`] query.
+///
+/// See [`AttributeKind::RustcDumpVtable`] for the internal representation of this attribute.
+///
+/// # Example
+///
+#[doc = include_example!("rustc_dump_vtable")]
+///
+/// [`vtable_entries`]: ../rustc_middle/ty/struct.TyCtxt.html#method.vtable_entries
+const _: () = ();

compiler/rustc_attr_ir/src/data_structures.rs

@@ -1219,46 +1219,46 @@ pub enum AttributeKind {
     /// Represents `#[rustc_dummy]`.
     RustcDummy,
 
-    /// Represents `#[rustc_dump_clauses]`
+    /// Represents the [`rustc_dump_clauses`](./attribute.rustc_dump_clauses.html) attribute.
     RustcDumpClauses,
 
-    /// Represents `#[rustc_dump_def_parents]`
+    /// Represents the [`rustc_dump_def_parents`](./attribute.rustc_dump_def_parents.html) attribute.
     RustcDumpDefParents,
 
-    /// Represents `#[rustc_dump_def_path]`
+    /// Represents the [`rustc_dump_def_path`](./attribute.rustc_dump_def_path.html) attribute.
     RustcDumpDefPath(Span),
 
-    /// Represents `#[rustc_dump_generics]`
+    /// Represents the [`rustc_dump_generics`](./attribute.rustc_dump_generics.html) attribute.
     RustcDumpGenerics,
 
-    /// Represents `#[rustc_dump_hidden_type_of_opaques]`
+    /// Represents the [`rustc_dump_hidden_type_of_opaques`](./attribute.rustc_dump_hidden_type_of_opaques.html) attribute.
     RustcDumpHiddenTypeOfOpaques,
 
-    /// Represents `#[rustc_dump_inferred_outlives]`
+    /// Represents the [`rustc_dump_inferred_outlives`](./attribute.rustc_dump_inferred_outlives.html) attribute.
     RustcDumpInferredOutlives,
 
-    /// Represents `#[rustc_dump_item_bounds]`
+    /// Represents the [`rustc_dump_item_bounds`](./attribute.rustc_dump_item_bounds.html) attribute.
     RustcDumpItemBounds,
 
-    /// Represents `#[rustc_dump_layout]`
+    /// Represents the [`rustc_dump_layout`](./attribute.rustc_dump_layout.html) attribute.
     RustcDumpLayout(ThinVec<RustcDumpLayoutKind>),
 
-    /// Represents `#[rustc_dump_object_lifetime_defaults]`.
+    /// Represents the [`rustc_dump_object_lifetime_defaults`](./attribute.rustc_dump_object_lifetime_defaults.html) attribute.
     RustcDumpObjectLifetimeDefaults,
 
-    /// Represents `#[rustc_dump_symbol_name]`
+    /// Represents the [`rustc_dump_symbol_name`](./attribute.rustc_dump_symbol_name.html) attribute.
     RustcDumpSymbolName(Span),
 
     /// Represents `#[rustc_dump_user_args]`
     RustcDumpUserArgs,
 
-    /// Represents `#[rustc_dump_variances]`
+    /// Represents the [`rustc_dump_variances`](./attribute.rustc_dump_variances.html) attribute.
     RustcDumpVariances,
 
-    /// Represents `#[rustc_dump_variances_of_opaques]`
+    /// Represents the [`rustc_dump_variances_of_opaques`](./attribute.rustc_dump_variances_of_opaques.html) attribute.
     RustcDumpVariancesOfOpaques,
 
-    /// Represents `#[rustc_dump_vtable]`
+    /// Represents the [`rustc_dump_vtable`](./attribute.rustc_dump_vtable.html) attribute.
     RustcDumpVtable(Span),
 
     /// Represents `#[rustc_dyn_incompatible_trait]`.

compiler/rustc_attr_ir/src/lib.rs

@@ -4,11 +4,13 @@
 //! see [rustc_attr_parsing](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_attr_parsing/index.html).
 
 // tidy-alphabetical-start
+#![expect(internal_features, reason = "rustdoc_internals, for documenting attributes")]
 #![feature(const_default)]
 #![feature(const_trait_impl)]
 #![feature(default_field_values)]
 #![feature(derive_const)]
 #![feature(exhaustive_patterns)]
+#![feature(rustdoc_internals)]
 #![feature(variant_count)]
 #![recursion_limit = "256"]
 // tidy-alphabetical-end
@@ -125,3 +127,5 @@ macro_rules! find_attr {
         }
     }};
 }
+
+include!("attribute_docs.rs");

src/bootstrap/src/bin/rustdoc.rs

@@ -72,11 +72,9 @@ fn main() {
                 .arg("-Zcrate-attr=doc(rust_logo)")
                 .arg("-Zcrate-attr=doc(html_root_url = \"https://doc.rust-lang.org/nightly/nightly-rustc/\")");
 
-            // rustc_proc_macro is another build of library/proc_macro which already enables this
-            // feature
-            if crate_name != "rustc_proc_macro" {
-                cmd.arg("-Zcrate-attr=feature(rustdoc_internals)");
-            }
+            // Some crates already have this feature enabled
+            cmd.arg("-Zcrate-attr=feature(rustdoc_internals)");
+            cmd.arg("-Aduplicate-features");
         }
     }
 

tests/ui/attributes/doc_examples/README.md

@@ -0,0 +1 @@
+These UI tests and their stderr are `include_str`'d into compiler/rustc_attr_ir/src/attribute_docs.rs.

tests/ui/attributes/doc_examples/rustc_dump_clauses.rs

@@ -0,0 +1,25 @@
+//@ dont-require-annotations: ERROR
+//@ compile-flags: --crate-type lib -Z ui-testing=no
+//@ normalize-stderr: "DefId\((\d+):(\d+)" -> "DefId(..:.."
+//@ normalize-stderr: "\[[A-Fa-f0-9]{4}\]" -> "[....]"
+
+#![feature(negative_impls)]
+#![feature(rustc_attrs)]
+
+#[rustc_dump_clauses]
+fn function<T: Send>(_t: T) {}
+
+#[rustc_dump_clauses]
+trait Trait: Sync {
+    #[rustc_dump_clauses]
+    type Assoc;
+}
+
+#[rustc_dump_clauses]
+struct X<'a, T: ?Sized, I: Iterator> {
+    x: &'a T,
+    y: &'a I::Item,
+}
+
+#[rustc_dump_clauses]
+impl<T: ?Sized, I> !Sync for X<'_, T, I> {}