rustdoc: Turn next_def_id comments into docs

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()`]: 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)

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 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.
+ ///
+ /// 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 {