From e5f1e8883af5efae2eaf12f7b25e3bfe5573ba47 Mon Sep 17 00:00:00 2001 From: Camelid Date: Fri, 19 Feb 2021 14:13:25 -0800 Subject: [PATCH 1/8] Improve lang item generated docs cc https://rust-lang.zulipchat.com/#narrow/stream/146229-wg-secure-code/topic/Is.20.60core.60.20part.20of.20the.20compiler.3F/near/226738260 --- compiler/rustc_hir/src/lang_items.rs | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/compiler/rustc_hir/src/lang_items.rs b/compiler/rustc_hir/src/lang_items.rs index 03524569ce7a9..cc168fc07a0b8 100644 --- a/compiler/rustc_hir/src/lang_items.rs +++ b/compiler/rustc_hir/src/lang_items.rs @@ -45,20 +45,25 @@ macro_rules! language_item_table { /// A representation of all the valid language items in Rust. #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash, Encodable, Decodable)] pub enum LangItem { - $($variant,)* + $( + #[doc = concat!("The `", stringify!($name), "` lang item.")] + $variant, + )* } } impl LangItem { /// Returns the `name` symbol in `#[lang = "$name"]`. - /// For example, `LangItem::EqTraitLangItem`, - /// that is `#[lang = "eq"]` would result in `sym::eq`. + /// For example, [`LangItem::PartialEq`]`.name()` + /// would result in [`sym::eq`] since it is `#[lang = "eq"]`. pub fn name(self) -> Symbol { match self { $( LangItem::$variant => $name, )* } } + /// The [group](LangItemGroup) that this lang item belongs to, + /// or `None` if it doesn't belong to a group. pub fn group(self) -> Option { use LangItemGroup::*; match self { @@ -67,15 +72,16 @@ macro_rules! language_item_table { } } + /// All of the language items in the current crate, defined or not. #[derive(HashStable_Generic, Debug)] pub struct LanguageItems { - /// Mappings from lang items to their possibly found `DefId`s. - /// The index corresponds to the order in `LangItem`. + /// Mappings from lang items to their possibly found [`DefId`]s. + /// The index corresponds to the order in [`LangItem`]. pub items: Vec>, /// Lang items that were not found during collection. pub missing: Vec, - /// Mapping from `LangItemGroup` discriminants to all - /// `DefId`s of lang items in that group. + /// Mapping from [`LangItemGroup`] discriminants to all + /// [`DefId`]s of lang items in that group. pub groups: [Vec; NUM_GROUPS], } @@ -103,13 +109,13 @@ macro_rules! language_item_table { self.items[it as usize].ok_or_else(|| format!("requires `{}` lang_item", it.name())) } + /// Returns the [`DefId`]s of all lang items in a group. pub fn group(&self, group: LangItemGroup) -> &[DefId] { self.groups[group as usize].as_ref() } $( - /// Returns the corresponding `DefId` for the lang item if it - /// exists. + #[doc = concat!("Returns the [`DefId`] of the `", stringify!($name), "` lang item if it is defined.")] #[allow(dead_code)] pub fn $method(&self) -> Option { self.items[LangItem::$variant as usize] @@ -140,7 +146,7 @@ impl HashStable for LangItem { /// /// About the `check_name` argument: passing in a `Session` would be simpler, /// because then we could call `Session::check_name` directly. But we want to -/// avoid the need for `librustc_hir` to depend on `librustc_session`, so we +/// avoid the need for `rustc_hir` to depend on `rustc_session`, so we /// use a closure instead. pub fn extract<'a, F>(check_name: F, attrs: &'a [ast::Attribute]) -> Option<(Symbol, Span)> where From 58758f0275172da24ee311e354cd9a7fe79c6e39 Mon Sep 17 00:00:00 2001 From: Camelid Date: Sun, 28 Feb 2021 11:53:55 -0800 Subject: [PATCH 2/8] Allow variant attributes in `enum_from_u32!` --- compiler/rustc_data_structures/src/macros.rs | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/compiler/rustc_data_structures/src/macros.rs b/compiler/rustc_data_structures/src/macros.rs index b918ed9458cda..48dfbba7504ef 100644 --- a/compiler/rustc_data_structures/src/macros.rs +++ b/compiler/rustc_data_structures/src/macros.rs @@ -9,11 +9,11 @@ macro_rules! static_assert_size { #[macro_export] macro_rules! enum_from_u32 { ($(#[$attr:meta])* pub enum $name:ident { - $($variant:ident = $e:expr,)* + $($(#[$var_attr:meta])* $variant:ident = $e:expr,)* }) => { $(#[$attr])* pub enum $name { - $($variant = $e),* + $($(#[$var_attr])* $variant = $e),* } impl $name { @@ -26,11 +26,11 @@ macro_rules! enum_from_u32 { } }; ($(#[$attr:meta])* pub enum $name:ident { - $($variant:ident,)* + $($(#[$var_attr:meta])* $variant:ident,)* }) => { $(#[$attr])* pub enum $name { - $($variant,)* + $($(#[$var_attr])* $variant,)* } impl $name { From da0099a9ff0a8ab1c208f166a3b1b8b07571d025 Mon Sep 17 00:00:00 2001 From: Camelid Date: Sun, 28 Feb 2021 11:56:16 -0800 Subject: [PATCH 3/8] Enable `extended_key_value_attributes` in `rustc_hir` --- compiler/rustc_hir/src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/compiler/rustc_hir/src/lib.rs b/compiler/rustc_hir/src/lib.rs index c69a9b063aeca..105a7e4a596f7 100644 --- a/compiler/rustc_hir/src/lib.rs +++ b/compiler/rustc_hir/src/lib.rs @@ -5,6 +5,7 @@ #![feature(crate_visibility_modifier)] #![feature(const_fn)] // For the unsizing cast on `&[]` #![feature(const_panic)] +#![feature(extended_key_value_attributes)] #![feature(in_band_lifetimes)] #![feature(once_cell)] #![feature(or_patterns)] From 4b3490f64d21947346529a09d8ca3bf1558ea42e Mon Sep 17 00:00:00 2001 From: Camelid Date: Sun, 28 Feb 2021 12:01:08 -0800 Subject: [PATCH 4/8] Convert some lang item comments to doc-comments --- compiler/rustc_hir/src/lang_items.rs | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/compiler/rustc_hir/src/lang_items.rs b/compiler/rustc_hir/src/lang_items.rs index cc168fc07a0b8..9301f622d6b46 100644 --- a/compiler/rustc_hir/src/lang_items.rs +++ b/compiler/rustc_hir/src/lang_items.rs @@ -38,7 +38,7 @@ macro_rules! expand_group { // So you probably just want to nip down to the end. macro_rules! language_item_table { ( - $( $variant:ident $($group:expr)?, $name:expr, $method:ident, $target:expr; )* + $( $(#[attr:meta])* $variant:ident $($group:expr)?, $name:expr, $method:ident, $target:expr; )* ) => { enum_from_u32! { @@ -47,6 +47,8 @@ macro_rules! language_item_table { pub enum LangItem { $( #[doc = concat!("The `", stringify!($name), "` lang item.")] + /// + $(#[attr])* $variant, )* } @@ -196,15 +198,15 @@ language_item_table! { Sized, sym::sized, sized_trait, Target::Trait; Unsize, sym::unsize, unsize_trait, Target::Trait; - // Trait injected by #[derive(PartialEq)], (i.e. "Partial EQ"). + /// Trait injected by `#[derive(PartialEq)]`, (i.e. "Partial EQ"). StructuralPeq, sym::structural_peq, structural_peq_trait, Target::Trait; - // Trait injected by #[derive(Eq)], (i.e. "Total EQ"; no, I will not apologize). + /// Trait injected by `#[derive(Eq)]`, (i.e. "Total EQ"; no, I will not apologize). StructuralTeq, sym::structural_teq, structural_teq_trait, Target::Trait; Copy, sym::copy, copy_trait, Target::Trait; Clone, sym::clone, clone_trait, Target::Trait; Sync, sym::sync, sync_trait, Target::Trait; DiscriminantKind, sym::discriminant_kind, discriminant_kind_trait, Target::Trait; - // The associated item of `trait DiscriminantKind`. + /// The associated item of the [`DiscriminantKind`] trait. Discriminant, sym::discriminant_type, discriminant_type, Target::AssocTy; PointeeTrait, sym::pointee_trait, pointee_trait, Target::Trait; @@ -279,7 +281,7 @@ language_item_table! { PanicInfo, sym::panic_info, panic_info, Target::Struct; PanicLocation, sym::panic_location, panic_location, Target::Struct; PanicImpl, sym::panic_impl, panic_impl, Target::Fn; - // libstd panic entry point. Necessary for const eval to be able to catch it + /// libstd panic entry point. Necessary for const eval to be able to catch it BeginPanic, sym::begin_panic, begin_panic_fn, Target::Fn; ExchangeMalloc, sym::exchange_malloc, exchange_malloc_fn, Target::Fn; @@ -301,7 +303,7 @@ language_item_table! { MaybeUninit, sym::maybe_uninit, maybe_uninit, Target::Union; - // Align offset for stride != 1; must not panic. + /// Align offset for stride != 1; must not panic. AlignOffset, sym::align_offset, align_offset_fn, Target::Fn; Termination, sym::termination, termination, Target::Trait; From 4900836ab75b877775905931eba586ea8f13935d Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 10 Mar 2021 09:02:40 -0800 Subject: [PATCH 5/8] Fix bug It needs to be a variable! Co-authored-by: Joshua Nelson --- compiler/rustc_hir/src/lang_items.rs | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/compiler/rustc_hir/src/lang_items.rs b/compiler/rustc_hir/src/lang_items.rs index 9301f622d6b46..d62920a925be0 100644 --- a/compiler/rustc_hir/src/lang_items.rs +++ b/compiler/rustc_hir/src/lang_items.rs @@ -38,7 +38,7 @@ macro_rules! expand_group { // So you probably just want to nip down to the end. macro_rules! language_item_table { ( - $( $(#[attr:meta])* $variant:ident $($group:expr)?, $name:expr, $method:ident, $target:expr; )* + $( $(#[$attr:meta])* $variant:ident $($group:expr)?, $name:expr, $method:ident, $target:expr; )* ) => { enum_from_u32! { @@ -48,7 +48,7 @@ macro_rules! language_item_table { $( #[doc = concat!("The `", stringify!($name), "` lang item.")] /// - $(#[attr])* + $(#[$attr])* $variant, )* } From b782939c06eb97bb276ce3cd4aac46eb1ebd511a Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 10 Mar 2021 09:05:59 -0800 Subject: [PATCH 6/8] Remove `sym::` and `kw::` from generated docs --- compiler/rustc_hir/src/lang_items.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/compiler/rustc_hir/src/lang_items.rs b/compiler/rustc_hir/src/lang_items.rs index d62920a925be0..84c874ee5373a 100644 --- a/compiler/rustc_hir/src/lang_items.rs +++ b/compiler/rustc_hir/src/lang_items.rs @@ -38,7 +38,7 @@ macro_rules! expand_group { // So you probably just want to nip down to the end. macro_rules! language_item_table { ( - $( $(#[$attr:meta])* $variant:ident $($group:expr)?, $name:expr, $method:ident, $target:expr; )* + $( $(#[$attr:meta])* $variant:ident $($group:expr)?, $module:ident :: $name:ident, $method:ident, $target:expr; )* ) => { enum_from_u32! { @@ -60,7 +60,7 @@ macro_rules! language_item_table { /// would result in [`sym::eq`] since it is `#[lang = "eq"]`. pub fn name(self) -> Symbol { match self { - $( LangItem::$variant => $name, )* + $( LangItem::$variant => $module::$name, )* } } @@ -128,7 +128,7 @@ macro_rules! language_item_table { /// A mapping from the name of the lang item to its order and the form it must be of. pub static ITEM_REFS: SyncLazy> = SyncLazy::new(|| { let mut item_refs = FxHashMap::default(); - $( item_refs.insert($name, (LangItem::$variant as usize, $target)); )* + $( item_refs.insert($module::$name, (LangItem::$variant as usize, $target)); )* item_refs }); From d31f70c87c4e6451eaf69009fcf62c4435bf4174 Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 10 Mar 2021 09:20:12 -0800 Subject: [PATCH 7/8] Clarify docs --- compiler/rustc_hir/src/lang_items.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/compiler/rustc_hir/src/lang_items.rs b/compiler/rustc_hir/src/lang_items.rs index 84c874ee5373a..e7a042a63489b 100644 --- a/compiler/rustc_hir/src/lang_items.rs +++ b/compiler/rustc_hir/src/lang_items.rs @@ -74,7 +74,8 @@ macro_rules! language_item_table { } } - /// All of the language items in the current crate, defined or not. + /// All of the language items, defined or not. + /// Defined lang items can come from the current crate or its dependencies. #[derive(HashStable_Generic, Debug)] pub struct LanguageItems { /// Mappings from lang items to their possibly found [`DefId`]s. From ab42f96cff0aa4264d72d8bc76b810b2a0046653 Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 10 Mar 2021 10:27:04 -0800 Subject: [PATCH 8/8] Remove unnecessary `#[allow(dead_code)]` --- compiler/rustc_hir/src/lang_items.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/compiler/rustc_hir/src/lang_items.rs b/compiler/rustc_hir/src/lang_items.rs index e7a042a63489b..498000db50f43 100644 --- a/compiler/rustc_hir/src/lang_items.rs +++ b/compiler/rustc_hir/src/lang_items.rs @@ -119,7 +119,6 @@ macro_rules! language_item_table { $( #[doc = concat!("Returns the [`DefId`] of the `", stringify!($name), "` lang item if it is defined.")] - #[allow(dead_code)] pub fn $method(&self) -> Option { self.items[LangItem::$variant as usize] }