From e636805eee49ff2e8bc30429ab91a8e2508656b3 Mon Sep 17 00:00:00 2001 From: Camelid Date: Tue, 5 Jan 2021 16:32:50 -0800 Subject: [PATCH 1/2] rustdoc: Turn `next_def_id` comments into docs --- src/librustdoc/clean/types.rs | 4 +++- src/librustdoc/core.rs | 22 ++++++++++++++-------- 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs index cc31461646cc9..0364bfd5951f7 100644 --- a/src/librustdoc/clean/types.rs +++ b/src/librustdoc/clean/types.rs @@ -291,7 +291,9 @@ impl Item { } } - /// See comments on next_def_id + /// See the documentation for [`next_def_id()`]. + /// + /// [`next_def_id()`]: crate::core::DocContext::next_def_id() crate fn is_fake(&self) -> bool { MAX_DEF_ID.with(|m| { m.borrow().get(&self.def_id.krate).map(|id| self.def_id >= *id).unwrap_or(false) diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 4aeca0faea76a..ac3b8895996b9 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -120,14 +120,20 @@ impl<'tcx> DocContext<'tcx> { r } - // This is an ugly hack, but it's the simplest way to handle synthetic impls without greatly - // refactoring either librustdoc or librustc_middle. In particular, allowing new DefIds to be - // registered after the AST is constructed would require storing the defid mapping in a - // RefCell, decreasing the performance for normal compilation for very little gain. - // - // Instead, we construct 'fake' def ids, which start immediately after the last DefId. - // In the Debug impl for clean::Item, we explicitly check for fake - // def ids, as we'll end up with a panic if we use the DefId Debug impl for fake DefIds + /// Create a new "fake" [`DefId`]. + /// + /// This is an ugly hack, but it's the simplest way to handle synthetic impls without greatly + /// refactoring either `librustdoc` or [`rustc_middle`]. In particular, allowing new [`DefId`]s + /// to be registered after the AST is constructed would require storing the [`DefId`] mapping + /// in a [`RefCell`], decreasing the performance for normal compilation for very little gain. + /// + /// Instead, we construct "fake" [`DefId`]s, which start immediately after the last `DefId`. + /// In the [`Debug`] impl for [`clean::Item`], we explicitly check for fake `DefId`s, + /// as we'll end up with a panic if we use the `DefId` `Debug` impl for fake `DefId`s. + /// + /// [`RefCell`]: std::cell::RefCell + /// [`Debug`]: std::fmt::Debug + /// [`clean::Item`]: crate::clean::types::Item crate fn next_def_id(&self, crate_num: CrateNum) -> DefId { let start_def_id = { let num_def_ids = if crate_num == LOCAL_CRATE { From 7428e2d1349fe03da821ee2181ccf7395b9cfe30 Mon Sep 17 00:00:00 2001 From: Camelid Date: Tue, 5 Jan 2021 19:46:51 -0800 Subject: [PATCH 2/2] Apply suggestions from code review Co-authored-by: Joshua Nelson --- src/librustdoc/clean/types.rs | 2 +- src/librustdoc/core.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/librustdoc/clean/types.rs b/src/librustdoc/clean/types.rs index 0364bfd5951f7..38791fcea5484 100644 --- a/src/librustdoc/clean/types.rs +++ b/src/librustdoc/clean/types.rs @@ -293,7 +293,7 @@ impl Item { /// See the documentation for [`next_def_id()`]. /// - /// [`next_def_id()`]: crate::core::DocContext::next_def_id() + /// [`next_def_id()`]: DocContext::next_def_id() crate fn is_fake(&self) -> bool { MAX_DEF_ID.with(|m| { m.borrow().get(&self.def_id.krate).map(|id| self.def_id >= *id).unwrap_or(false) diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index ac3b8895996b9..43aaefa087073 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -123,7 +123,7 @@ impl<'tcx> DocContext<'tcx> { /// Create a new "fake" [`DefId`]. /// /// This is an ugly hack, but it's the simplest way to handle synthetic impls without greatly - /// refactoring either `librustdoc` or [`rustc_middle`]. In particular, allowing new [`DefId`]s + /// refactoring either rustdoc or [`rustc_middle`]. In particular, allowing new [`DefId`]s /// to be registered after the AST is constructed would require storing the [`DefId`] mapping /// in a [`RefCell`], decreasing the performance for normal compilation for very little gain. ///