Add note motivating Iterator

containers/src/Data/Map/Internal.hs

@@ -4092,6 +4092,8 @@ deleteFindMax t = case maxViewWithKey t of
   Iterator
 --------------------------------------------------------------------}
 
+-- See Note [Iterator] in Data.Set.Internal
+
 newtype Iterator k a = Iterator (Stack k a)
 
 iterDown :: Map k a -> Stack k a -> Stack k a

containers/src/Data/Set/Internal.hs

@@ -1267,6 +1267,18 @@ foldl'Stack f = go
   Iterator
 --------------------------------------------------------------------}
 
+-- Note [Iterator]
+-- ~~~~~~~~~~~~~~~
+-- This is an efficient way to consume a Set one element at a time.
+-- Alternately, this may be done by toAscList. toAscList when consumed via
+-- List.foldr will rewrite to Set.foldr (thanks to rewrite rules), which is
+-- quite efficient. However, sometimes that is not possible, such as in the
+-- second arg of '==' or 'compare', where manifesting the list cons cells
+-- is unavoidable and makes things slower.
+--
+-- Concretely, compare on Set Int using toAscList takes ~21% more time compared
+-- to using Iterator, on GHC 9.6.3.
+
 newtype Iterator a = Iterator (Stack a)
 
 iterDown :: Set a -> Stack a -> Stack a