From e636805eee49ff2e8bc30429ab91a8e2508656b3 Mon Sep 17 00:00:00 2001
From: Camelid <camelidcamel@gmail.com>
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 <camelidcamel@gmail.com>
Date: Tue, 5 Jan 2021 19:46:51 -0800
Subject: [PATCH 2/2] Apply suggestions from code review

Co-authored-by: Joshua Nelson <joshua@yottadb.com>
---
 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.
     ///