add doc-comment

Author: AlexWaygood

crates/ty_python_semantic/src/types/cyclic.rs

@@ -21,8 +21,19 @@ pub(crate) type PairVisitor<'db> = CycleDetector<(Type<'db>, Type<'db>), bool>;
 
 #[derive(Debug)]
 pub(crate) struct CycleDetector<T, R> {
+    /// If the type we're visiting is present in `seen`,
+    /// it indicates that we've hit a cycle (due to a recursive type);
+    /// we need to immediately short circuit the whole operation and return the fallback value.
+    /// That's why we pop items off the end of `seen` after we've visited them.
     seen: FxIndexSet<T>,
+
+    /// Unlike `seen`, this field is a pure performance optimisation (and an essential one).
+    /// If the type we're trying to normalize is present in `cache`, it doesn't necessarily mean we've hit a cycle:
+    /// it just means that we've already visited this inner type as part of a bigger call chain we're currently in.
+    /// Since this cache is just a performance optimisation, it doesn't make sense to pop items off the end of the
+    /// cache after they've been visited (it would sort-of defeat the point of a cache if we did!)
     cache: FxHashMap<T, R>,
+
     fallback: R,
 }