Small improvements to internal documentation

compiler/rustc_middle/src/ty/instance.rs

@@ -414,6 +414,7 @@ impl<'tcx> fmt::Display for Instance<'tcx> {
 }
 
 impl<'tcx> Instance<'tcx> {
+    /// Creates a new instance of type `InstanceDef::Item`, with appropiate `def_id` and `args` set.
     pub fn new(def_id: DefId, args: GenericArgsRef<'tcx>) -> Instance<'tcx> {
         assert!(
             !args.has_escaping_bound_vars(),
@@ -437,6 +438,7 @@ impl<'tcx> Instance<'tcx> {
         Instance::new(def_id, args)
     }
 
+    /// Returns the `def_id` of this instance.
     #[inline]
     pub fn def_id(&self) -> DefId {
         self.def.def_id()
@@ -482,6 +484,7 @@ impl<'tcx> Instance<'tcx> {
         tcx.resolve_instance(tcx.erase_regions(param_env.and((def_id, args))))
     }
 
+    /// Behaves exactly like [`Self::resolve`], but panics on error.
     pub fn expect_resolve(
         tcx: TyCtxt<'tcx>,
         param_env: ty::ParamEnv<'tcx>,
@@ -618,6 +621,7 @@ impl<'tcx> Instance<'tcx> {
         }
     }
 
+    /// Returns an instance representing closure of type `requested_kind` with `def_id` and subst set to `args`.
     pub fn resolve_closure(
         tcx: TyCtxt<'tcx>,
         def_id: DefId,
@@ -632,6 +636,7 @@ impl<'tcx> Instance<'tcx> {
         }
     }
 
+    /// Returns an instance representing the function [`core::ptr::drop_in_place`] with its generic argument set to `ty`.
     pub fn resolve_drop_in_place(tcx: TyCtxt<'tcx>, ty: Ty<'tcx>) -> ty::Instance<'tcx> {
         let def_id = tcx.require_lang_item(LangItem::DropInPlace, None);
         let args = tcx.mk_args(&[ty.into()]);
@@ -741,6 +746,10 @@ impl<'tcx> Instance<'tcx> {
         self.def.has_polymorphic_mir_body().then_some(self.args)
     }
 
+    /// Instantiates a generic value `v`(like `Vec<T>`), substituting its generic arguments and turning it into a concrete one(like `i32`, or `Vec<f32>`).
+    /// If a value is not generic, this will do nothing.
+    /// This function does not erase lifetimes, so a value like `&'a i32` will remain unchanged.
+    /// For monomorphizing generics while also erasing lifetimes, try using [`Self::instantiate_mir_and_normalize_erasing_regions`].
     pub fn instantiate_mir<T>(&self, tcx: TyCtxt<'tcx>, v: EarlyBinder<&T>) -> T
     where
         T: TypeFoldable<TyCtxt<'tcx>> + Copy,
@@ -753,6 +762,11 @@ impl<'tcx> Instance<'tcx> {
         }
     }
 
+    /// Instantiates a generic value `v`(like `Vec<T>`), substituting its generic arguments and turning it into a concrete one(like `i32`, or `Vec<f32>`).
+    /// This function erases lifetimes, so a value like `&'a i32` will become `&ReErased i32`.
+    /// If a value is not generic and has no lifetime info, this will do nothing.
+    /// For monomorphizing generics while preserving lifetimes, use [`Self::instantiate_mir`].
+    /// This function will panic if normalization fails. If you want to handle normalization errors, use [`Self::try_instantiate_mir_and_normalize_erasing_regions`]
     #[inline(always)]
     // Keep me in sync with try_instantiate_mir_and_normalize_erasing_regions
     pub fn instantiate_mir_and_normalize_erasing_regions<T>(
@@ -771,6 +785,7 @@ impl<'tcx> Instance<'tcx> {
         }
     }
 
+    /// A version of [`Self::instantiate_mir_and_normalize_erasing_regions`] which will returns a [`NormalizationError`] on normalization failure instead of panicking.
     #[inline(always)]
     // Keep me in sync with instantiate_mir_and_normalize_erasing_regions
     pub fn try_instantiate_mir_and_normalize_erasing_regions<T>(
@@ -939,6 +954,7 @@ fn needs_fn_once_adapter_shim(
 
 // Set bits represent unused generic parameters.
 // An empty set indicates that all parameters are used.
+/// A data structure used to store information about which generic parameters are in use, and which are not.
 #[derive(Debug, Copy, Clone, Eq, PartialEq, Decodable, Encodable, HashStable)]
 pub struct UnusedGenericParams(FiniteBitSet<u32>);
 
@@ -949,36 +965,44 @@ impl Default for UnusedGenericParams {
 }
 
 impl UnusedGenericParams {
+    /// Creates a new [`UnusedGenericParams`] where all generic pameters are set as unused.
     pub fn new_all_unused(amount: u32) -> Self {
         let mut bitset = FiniteBitSet::new_empty();
         bitset.set_range(0..amount);
         Self(bitset)
     }
 
+    /// Creates a new [`UnusedGenericParams`] where all generic pameters are set as used.
     pub fn new_all_used() -> Self {
         Self(FiniteBitSet::new_empty())
     }
 
+    /// Marks a generic paramenter at index `idx` as used.
     pub fn mark_used(&mut self, idx: u32) {
         self.0.clear(idx);
     }
 
+    /// Returns true if generic paramenter at index `idx` unused, and false otherwise.
     pub fn is_unused(&self, idx: u32) -> bool {
         self.0.contains(idx).unwrap_or(false)
     }
 
+    /// Returns true if generic paramenter at index `idx` used, and false otherwise.
     pub fn is_used(&self, idx: u32) -> bool {
         !self.is_unused(idx)
     }
 
+    /// Returns true if all generic parameters are used, and false otherwise.
     pub fn all_used(&self) -> bool {
         self.0.is_empty()
     }
 
+    /// Turns a [`UnusedGenericParams`] into its underlying bit representation.
     pub fn bits(&self) -> u32 {
         self.0.0
     }
 
+    /// Creates a [`UnusedGenericParams`] from its bit representation.
     pub fn from_bits(bits: u32) -> UnusedGenericParams {
         UnusedGenericParams(FiniteBitSet(bits))
     }