From 98cd031816eb8cf253b71d95f6e251bceea3444a Mon Sep 17 00:00:00 2001
From: Waffle Lapkin <waffle.lapkin@gmail.com>
Date: Thu, 2 Jan 2025 19:15:23 +0100
Subject: [PATCH] Add a doc comment for `super_traits`

Co-authored-by: Ryo Yoshida <low.ryoshida@gmail.com>
---
 chalk-solve/src/clauses/super_traits.rs | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/chalk-solve/src/clauses/super_traits.rs b/chalk-solve/src/clauses/super_traits.rs
index fd700ca3873..1b4d5b1fc4b 100644
--- a/chalk-solve/src/clauses/super_traits.rs
+++ b/chalk-solve/src/clauses/super_traits.rs
@@ -73,6 +73,27 @@ pub(super) fn push_trait_super_clauses<I: Interner>(
     }
 }
 
+/// Returns super-`TraitRef`s and super-`Projection`s that are quantified over the parameters of
+/// `trait_id` and relevant higher-ranked lifetimes. The outer `Binders` is for the former and the
+/// inner `Binders` is for the latter.
+///
+/// For example, given the following trait definitions and `C` as `trait_id`,
+///
+/// ```
+/// trait A<'a, T> {}
+/// trait B<'b, U> where Self: for<'x> A<'x, U> {}
+/// trait C<'c, V> where Self: B<'c, V> {}
+/// ```
+///
+/// returns the following quantified `TraitRef`s.
+///
+/// ```notrust
+/// for<Self, 'c, V> {
+///     for<'x> { Self: A<'x, V> }
+///     for<> { Self: B<'c, V> }
+///     for<> { Self: C<'c, V> }
+/// }
+/// ```
 pub(crate) fn super_traits<I: Interner>(
     db: &dyn RustIrDatabase<I>,
     trait_id: TraitId<I>,