Rollup merge of #73787 - pickfire:rustc-attrs, r=RalfJung

Add unstable docs for rustc_attrs

r? @RalfJung

1 files changed, 53 insertions, 0 deletions

diff --git a/src/doc/unstable-book/src/language-features/rustc-attrs.md b/src/doc/unstable-book/src/language-features/rustc-attrs.md
new file mode 100644
index 00000000000..2967200faf8
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/rustc-attrs.md
@@ -0,0 +1,53 @@
+# `rustc_attrs`
+
+This feature has no tracking issue, and is therefore internal to
+the compiler, not being intended for general use.
+
+Note: `rustc_attrs` enables many rustc-internal attributes and this page
+only discuss a few of them.
+
+------------------------
+
+The `rustc_attrs` feature allows debugging rustc type layouts by using
+`#[rustc_layout(...)]` to debug layout at compile time (it even works
+with `cargo check`) as an alternative to `rustc -Z print-type-sizes`
+that is way more verbose.
+
+Options provided by `#[rustc_layout(...)]` are `debug`, `size`, `abi`.
+Note that it only work best with sized type without generics.
+
+## Examples
+
+```rust,ignore
+#![feature(rustc_attrs)]
+
+#[rustc_layout(abi, size)]
+pub enum X {
+    Y(u8, u8, u8),
+    Z(isize),
+}
+```
+
+When that is compiled, the compiler will error with something like
+
+```text
+error: abi: Aggregate { sized: true }
+ --> src/lib.rs:4:1
+  |
+4 | / pub enum T {
+5 | |     Y(u8, u8, u8),
+6 | |     Z(isize),
+7 | | }
+  | |_^
+
+error: size: Size { raw: 16 }
+ --> src/lib.rs:4:1
+  |
+4 | / pub enum T {
+5 | |     Y(u8, u8, u8),
+6 | |     Z(isize),
+7 | | }
+  | |_^
+
+error: aborting due to 2 previous errors
+```