Document all public items in chalk-ir

chalk-ir/src/cast.rs

@@ -1,3 +1,5 @@
+//! Upcasts, to avoid writing out wrapper types.
+
 use crate::*;
 use std::marker::PhantomData;
 
@@ -38,6 +40,7 @@ use std::marker::PhantomData;
 /// This split setup allows us to write `foo.cast::<T>()` to mean
 /// "cast to T".
 pub trait Cast: Sized {
+    /// Cast a value to type `U` using `CastTo`.
     fn cast<U>(self, interner: &U::Interner) -> U
     where
         Self: CastTo<U>,
@@ -54,6 +57,7 @@ impl<T> Cast for T {}
 /// functions that take (e.g.) an `impl CastTo<Goal<_>>` or something
 /// like that.
 pub trait CastTo<T: HasInterner>: Sized {
+    /// Cast a value to type `T`.
     fn cast_to(self, interner: &T::Interner) -> T;
 }
 
@@ -333,6 +337,7 @@ where
     }
 }
 
+/// An iterator that casts each element to some other type.
 pub struct Casted<'i, IT, U: HasInterner> {
     interner: &'i U::Interner,
     iterator: IT,
@@ -358,6 +363,7 @@ where
 /// An iterator adapter that casts each element we are iterating over
 /// to some other type.
 pub trait Caster: Iterator + Sized {
+    /// Cast each element in this iterator.
     fn casted<U>(self, interner: &U::Interner) -> Casted<'_, Self, U>
     where
         Self::Item: CastTo<U>,

chalk-ir/src/could_match.rs

@@ -1,9 +1,12 @@
+//! Fast matching check for zippable values.
+
 use crate::interner::HasInterner;
 use crate::zip::{Zip, Zipper};
 use crate::*;
 
 /// A fast check to see whether two things could ever possibly match.
 pub trait CouldMatch<T: ?Sized + HasInterner> {
+    /// Checks whether `self` and `other` could possibly match.
     fn could_match(&self, interner: &T::Interner, other: &T) -> bool;
 }
 

chalk-ir/src/debug.rs

@@ -1,3 +1,5 @@
+//! Debug impls for types.
+
 use std::fmt::{Debug, Display, Error, Formatter};
 
 use super::*;
@@ -251,6 +253,7 @@ impl<I: Interner> VariableKinds<I> {
         VariableKindsDebug(self)
     }
 
+    /// Helper method for debugging variable kinds.
     pub fn inner_debug<'a>(&'a self, interner: &'a I) -> VariableKindsInnerDebug<'a, I> {
         VariableKindsInnerDebug {
             variable_kinds: self,
@@ -268,6 +271,7 @@ impl<'a, I: Interner> Debug for VariableKindsDebug<'a, I> {
     }
 }
 
+/// Helper struct for showing debug output for `VariableKinds`.
 pub struct VariableKindsInnerDebug<'a, I: Interner> {
     variable_kinds: &'a VariableKinds<I>,
     interner: &'a I,
@@ -327,6 +331,7 @@ impl<I: Interner> Debug for GoalData<I> {
     }
 }
 
+/// Helper struct for showing debug output for `Goals`.
 pub struct GoalsDebug<'a, I: Interner> {
     goals: &'a Goals<I>,
     interner: &'a I,
@@ -347,6 +352,7 @@ impl<'a, I: Interner> Debug for GoalsDebug<'a, I> {
 }
 
 impl<I: Interner> Goals<I> {
+    /// Show debug output for `Goals`.
     pub fn debug<'a>(&'a self, interner: &'a I) -> GoalsDebug<'a, I> {
         GoalsDebug {
             goals: self,
@@ -355,6 +361,7 @@ impl<I: Interner> Goals<I> {
     }
 }
 
+/// Helper struct for showing debug output for `GenericArgData`.
 pub struct GenericArgDataInnerDebug<'a, I: Interner>(&'a GenericArgData<I>);
 
 impl<'a, I: Interner> Debug for GenericArgDataInnerDebug<'a, I> {
@@ -368,11 +375,13 @@ impl<'a, I: Interner> Debug for GenericArgDataInnerDebug<'a, I> {
 }
 
 impl<I: Interner> GenericArgData<I> {
+    /// Helper method for debugging `GenericArgData`.
     pub fn inner_debug(&self) -> GenericArgDataInnerDebug<'_, I> {
         GenericArgDataInnerDebug(self)
     }
 }
 
+/// Helper struct for showing debug output for program clause implications.
 pub struct ProgramClauseImplicationDebug<'a, I: Interner> {
     pci: &'a ProgramClauseImplication<I>,
     interner: &'a I,
@@ -399,6 +408,7 @@ impl<'a, I: Interner> Debug for ProgramClauseImplicationDebug<'a, I> {
 }
 
 impl<I: Interner> ProgramClauseImplication<I> {
+    /// Show debug output for the program clause implication.
     pub fn debug<'a>(&'a self, interner: &'a I) -> ProgramClauseImplicationDebug<'a, I> {
         ProgramClauseImplicationDebug {
             pci: self,
@@ -407,6 +417,7 @@ impl<I: Interner> ProgramClauseImplication<I> {
     }
 }
 
+/// Helper struct for showing debug output for application types.
 pub struct ApplicationTyDebug<'a, I: Interner> {
     application_ty: &'a ApplicationTy<I>,
     interner: &'a I,
@@ -424,6 +435,7 @@ impl<'a, I: Interner> Debug for ApplicationTyDebug<'a, I> {
 }
 
 impl<I: Interner> ApplicationTy<I> {
+    /// Show debug output for the application type.
     pub fn debug<'a>(&'a self, interner: &'a I) -> ApplicationTyDebug<'a, I> {
         ApplicationTyDebug {
             application_ty: self,
@@ -432,6 +444,7 @@ impl<I: Interner> ApplicationTy<I> {
     }
 }
 
+/// Helper struct for showing debug output for substitutions.
 pub struct SubstitutionDebug<'a, I: Interner> {
     substitution: &'a Substitution<I>,
     interner: &'a I,
@@ -464,6 +477,7 @@ impl<'a, I: Interner> Debug for SubstitutionDebug<'a, I> {
 }
 
 impl<I: Interner> Substitution<I> {
+    ///
     pub fn debug<'a>(&'a self, interner: &'a I) -> SubstitutionDebug<'a, I> {
         SubstitutionDebug {
             substitution: self,
@@ -503,11 +517,16 @@ impl<I: Interner> Debug for TraitRef<I> {
     }
 }
 
+/// Trait ref with associated separator used for debug output.
 pub struct SeparatorTraitRef<'me, I: Interner> {
+    /// The `TraitRef` itself
     pub trait_ref: &'me TraitRef<I>,
+
+    /// The separator used for displaying the `TraitRef`
     pub separator: &'me str,
 }
 
+/// Helper struct for showing debug output for the `SeperatorTraitRef`
 pub struct SeparatorTraitRefDebug<'a, 'me, I: Interner> {
     separator_trait_ref: &'a SeparatorTraitRef<'me, I>,
     interner: &'a I,
@@ -535,6 +554,7 @@ impl<'a, 'me, I: Interner> Debug for SeparatorTraitRefDebug<'a, 'me, I> {
 }
 
 impl<'me, I: Interner> SeparatorTraitRef<'me, I> {
+    /// Show debug output for the `SeperatorTraitRef`
     pub fn debug<'a>(&'a self, interner: &'a I) -> SeparatorTraitRefDebug<'a, 'me, I> {
         SeparatorTraitRefDebug {
             separator_trait_ref: self,
@@ -549,6 +569,7 @@ impl<I: Interner> Debug for LifetimeOutlives<I> {
     }
 }
 
+/// Helper struct for showing debug output for projection types.
 pub struct ProjectionTyDebug<'a, I: Interner> {
     projection_ty: &'a ProjectionTy<I>,
     interner: &'a I,
@@ -570,6 +591,7 @@ impl<'a, I: Interner> Debug for ProjectionTyDebug<'a, I> {
 }
 
 impl<I: Interner> ProjectionTy<I> {
+    /// Show debug output for the projection type.
     pub fn debug<'a>(&'a self, interner: &'a I) -> ProjectionTyDebug<'a, I> {
         ProjectionTyDebug {
             projection_ty: self,
@@ -578,6 +600,7 @@ impl<I: Interner> ProjectionTy<I> {
     }
 }
 
+/// Helper struct for showing debug output for opaque types.
 pub struct OpaqueTyDebug<'a, I: Interner> {
     opaque_ty: &'a OpaqueTy<I>,
     interner: &'a I,
@@ -599,6 +622,7 @@ impl<'a, I: Interner> Debug for OpaqueTyDebug<'a, I> {
 }
 
 impl<I: Interner> OpaqueTy<I> {
+    /// Show debug output for the opaque type
     pub fn debug<'a>(&'a self, interner: &'a I) -> OpaqueTyDebug<'a, I> {
         OpaqueTyDebug {
             opaque_ty: self,
@@ -607,6 +631,7 @@ impl<I: Interner> OpaqueTy<I> {
     }
 }
 
+/// Wraps debug output in angle brackets (`<>`)
 pub struct Angle<'a, T>(pub &'a [T]);
 
 impl<'a, T: Debug> Debug for Angle<'a, T> {
@@ -724,6 +749,7 @@ impl<I: Interner> Debug for CanonicalVarKinds<I> {
 }
 
 impl<T: HasInterner + Display> Canonical<T> {
+    /// Display the canonicalized item.
     pub fn display<'a>(&'a self, interner: &'a T::Interner) -> CanonicalDisplay<'a, T> {
         CanonicalDisplay {
             canonical: self,
@@ -732,6 +758,7 @@ impl<T: HasInterner + Display> Canonical<T> {
     }
 }
 
+/// Helper struct for displaying canonicalized items.
 pub struct CanonicalDisplay<'a, T: HasInterner> {
     canonical: &'a Canonical<T>,
     interner: &'a T::Interner,

chalk-ir/src/fold.rs

@@ -172,6 +172,7 @@ where
         }
     }
 
+    /// As `fold_free_var_ty`, but for constants.
     fn fold_free_var_const(
         &mut self,
         ty: &Ty<I>,
@@ -233,6 +234,7 @@ where
         }
     }
 
+    /// As with `fold_free_placeholder_ty`, but for constants.
     #[allow(unused_variables)]
     fn fold_free_placeholder_const(
         &mut self,
@@ -278,7 +280,7 @@ where
         }
     }
 
-    /// As with `fold_free_inference_ty`, but for lifetimes.
+    /// As with `fold_inference_ty`, but for lifetimes.
     #[allow(unused_variables)]
     fn fold_inference_lifetime(
         &mut self,
@@ -292,6 +294,7 @@ where
         }
     }
 
+    /// As with `fold_inference_ty`, but for constants.
     #[allow(unused_variables)]
     fn fold_inference_const(
         &mut self,
@@ -309,8 +312,10 @@ where
         }
     }
 
+    /// Gets the interner that is being folded from.
     fn interner(&self) -> &'i I;
 
+    /// Gets the interner that is being folded to.
     fn target_interner(&self) -> &'i TI;
 }
 
@@ -356,6 +361,7 @@ pub trait Fold<I: Interner, TI: TargetInterner<I> = I>: Debug {
 /// `SuperFold` trait captures the recursive behavior that folds all
 /// the contents of the type.
 pub trait SuperFold<I: Interner, TI: TargetInterner<I> = I>: Fold<I, TI> {
+    /// Recursively folds the value
     fn super_fold_with<'i>(
         &self,
         folder: &mut dyn Folder<'i, I, TI>,

chalk-ir/src/fold/boring_impls.rs

@@ -213,6 +213,7 @@ impl<I: Interner, TI: TargetInterner<I>> Fold<I, TI> for QuantifiedWhereClauses<
     }
 }
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! copy_fold {
     ($t:ty) => {
@@ -247,6 +248,7 @@ copy_fold!(Scalar);
 copy_fold!(ClausePriority);
 copy_fold!(Mutability);
 
+#[doc(hidden)]
 #[macro_export]
 macro_rules! id_fold {
     ($t:ident) => {

chalk-ir/src/fold/shift.rs

@@ -1,3 +1,5 @@
+//! Shifting of debruijn indices
+
 use super::Fold;
 use crate::*;
 

chalk-ir/src/fold/subst.rs

@@ -1,6 +1,7 @@
 use super::*;
 use crate::fold::shift::Shift;
 
+/// Substitution used during folding
 pub struct Subst<'s, 'i, I: Interner> {
     /// Values to substitute. A reference to a free variable with
     /// index `i` will be mapped to `parameters[i]` -- if `i >
@@ -10,6 +11,7 @@ pub struct Subst<'s, 'i, I: Interner> {
 }
 
 impl<I: Interner> Subst<'_, '_, I> {
+    /// Applies the substitution by folding
     pub fn apply<T: Fold<I, I>>(
         interner: &I,
         parameters: &[GenericArg<I>],