Improve documentation and fix the fixme comment

Author: celinval

compiler/rustc_smir/src/rustc_smir/mod.rs

@@ -256,6 +256,9 @@ impl<'tcx> Context for TablesWrapper<'tcx> {
         tables.tcx.symbol_name(instance).name.to_string()
     }
 
+    /// Retrieve the instance name for diagnostic messages.
+    ///
+    /// This will return the specialized name, e.g., `Vec<char>::new`.
     fn instance_name(&self, def: InstanceDef, trimmed: bool) -> Symbol {
         let tables = self.0.borrow_mut();
         let instance = tables.instances[def];

compiler/stable_mir/src/crate_def.rs

@@ -1,4 +1,5 @@
-//! Module that define a common trait for things that represent a crate definition.
+//! Module that define a common trait for things that represent a crate definition,
+//! such as, a function, a trait, an enum, and any other definitions.
 
 use crate::ty::Span;
 use crate::{with, Crate, Symbol};
@@ -7,21 +8,23 @@ use crate::{with, Crate, Symbol};
 #[derive(Clone, Copy, PartialEq, Eq, Hash)]
 pub struct DefId(pub(crate) usize);
 
-/// A trait for retrieving information about a crate definition.
+/// A trait for retrieving information about a particular definition.
 ///
 /// Implementors must provide the implementation of `def_id` which will be used to retrieve
-/// information about its definition.
+/// information about a crate's definition.
 pub trait CrateDef {
-    /// Retrieve the unique identifier for the given definition.
+    /// Retrieve the unique identifier for the current definition.
     fn def_id(&self) -> DefId;
 
-    /// Return the fully qualified name of the given definition.
+    /// Return the fully qualified name of the current definition.
     fn name(&self) -> Symbol {
         let def_id = self.def_id();
         with(|cx| cx.def_name(def_id, false))
     }
 
-    /// Return a trimmed name of the given definition.
+    /// Return a trimmed name of this definition.
+    ///
+    /// This can be used to print more user friendly diagnostic messages.
     ///
     /// If a symbol name can only be imported from one place for a type, and as
     /// long as it was not glob-imported anywhere in the current crate, we trim its

compiler/stable_mir/src/mir/mono.rs

@@ -48,10 +48,16 @@ impl Instance {
         with(|context| context.instance_ty(self.def))
     }
 
+    /// Retrieve the instance's mangled name used for calling the given instance.
+    ///
+    /// This will also look up the correct name of instances from upstream crates.
     pub fn mangled_name(&self) -> Symbol {
         with(|context| context.instance_mangled_name(self.def))
     }
 
+    /// Retrieve the instance name for diagnostic messages.
+    ///
+    /// This will return the specialized name, e.g., `std::vec::Vec<u8>::new`.
     pub fn name(&self) -> Symbol {
         with(|context| context.instance_name(self.def, false))
     }
@@ -118,8 +124,8 @@ impl TryFrom<CrateItem> for Instance {
 
     fn try_from(item: CrateItem) -> Result<Self, Self::Error> {
         with(|context| {
-            /// FIXME(celinval):
-            /// - Check `has_body`.
+            // FIXME(celinval):
+            // - Return `Err` if instance does not have a body.
             if !context.requires_monomorphization(item.0) {
                 Ok(context.mono_instance(item))
             } else {