add comments

Author: auguste-probabl

skore/src/skore/_utils/_progress_bar.py

@@ -38,10 +38,16 @@ def progress_decorator(
     def decorator(func: Callable[..., T]) -> Callable[..., T]:
         @wraps(func)
         def wrapper(*args: Any, **kwargs: Any) -> T:
+            # Avoid circular import
             from skore import ComparisonReport
 
+            # The object to which a `rich.Progress` instance will be attached.
+            # Expected to be a Report
+            # (EstimatorReport | CrossValidationReport | ComparisonReport)
             self_obj: Any = args[0]
 
+            # If the decorated method is in an Accessor (e.g. MetricsAccessor),
+            # then make sure `self_obj` is the Report, not the Accessor.
             if hasattr(self_obj, "_parent"):
                 # self_obj is an accessor
                 self_obj = self_obj._parent
@@ -67,7 +73,8 @@ def wrapper(*args: Any, **kwargs: Any) -> T:
                 progress.start()
                 created_progress = True
 
-            # assigning progress to child reports
+            # Make child reports share their parent's Progress instance
+            # so that there is only one Progress instance at any given point
             reports_to_cleanup: list[Any] = []
             if isinstance(self_obj, ComparisonReport):
                 for report in self_obj.reports_.values():