Fuss over the comments on CanonAbi some more

Author: workingjubilee

compiler/rustc_abi/src/canon_abi.rs

@@ -102,8 +102,9 @@ impl fmt::Display for CanonAbi {
 impl CanonAbi {
     /// convert to the ExternAbi that *shares a string* with this CanonAbi
     ///
-    /// NOT correct to use if you want to map CanonAbi to an ABI it may have been lowered from,
-    /// but it is convenient for various "forwarding" implementations. Avoid exposing publicly!
+    /// A target-insensitive mapping of CanonAbi to ExternAbi, convenient for "forwarding" impls.
+    /// Importantly, the set of CanonAbi values is a logical *subset* of ExternAbi values,
+    /// so this is injective: if you take an ExternAbi to a CanonAbi and back, you have lost data.
     const fn to_erased_extern_abi(self) -> ExternAbi {
         match self {
             CanonAbi::C => ExternAbi::C { unwind: false },
@@ -136,8 +137,8 @@ impl CanonAbi {
 
     /// convert an ExternAbi to a CanonAbi if it maps directly
     ///
-    /// Like `to_erased_extern_abi`, this is only intended for internal usage by
-    /// CanonAbi's implementation, as it is not "target-aware".
+    /// A target-insensitive mapping of ExternAbi to CanonAbi. This is a partial function,
+    /// and mostly serves as a way to reuse ExternAbi's code.
     const fn try_from_extern_abi(extern_abi: ExternAbi) -> Result<Self, AbiConvErr> {
         match extern_abi {
             ExternAbi::C { unwind: false } => Ok(Self::C),