docs: clarify source filter page logic

- Explain source initialization
- Describe checkbox behavior
- Clarify apply button logic

Author: fulleni

lib/headlines-feed/view/source_filter_page.dart

@@ -30,8 +30,12 @@ class SourceFilterPage extends StatefulWidget {
 /// Manages the local selection state ([_pageSelectedSources]) and interacts
 /// with [SourcesFilterBloc] for data fetching and pagination.
 class _SourceFilterPageState extends State<SourceFilterPage> {
-  /// Stores the sources selected by the user on this page.
-  /// Initialized from the `extra` parameter passed during navigation.
+  /// Stores the sources selected by the user *on this specific page*.
+  /// This state is local to the `SourceFilterPage` lifecycle.
+  /// It's initialized in `initState` using the list of previously selected
+  /// sources passed via the `extra` parameter during navigation from
+  /// `HeadlinesFilterPage`. This ensures the checkboxes reflect the state
+  /// from the main filter page when this page loads.
   late Set<Source> _pageSelectedSources;
 
   /// Scroll controller to detect when the user reaches the end of the list
@@ -41,13 +45,27 @@ class _SourceFilterPageState extends State<SourceFilterPage> {
   @override
   void initState() {
     super.initState();
-    // Initialize local selections from the data passed via 'extra'
+    // Initialization needs to happen after the first frame to safely access
+    // GoRouterState.of(context).
     WidgetsBinding.instance.addPostFrameCallback((_) {
+      // 1. Retrieve the list of sources that were already selected on the
+      //    previous page (HeadlinesFilterPage). This list is passed dynamically
+      //    via the `extra` parameter in the `context.pushNamed` call.
       final initialSelection = GoRouterState.of(context).extra as List<Source>?;
+
+      // 2. Initialize the local selection state (`_pageSelectedSources`) for this
+      //    page. Use a Set for efficient add/remove/contains operations.
+      //    This ensures the checkboxes on this page are initially checked
+      //    correctly based on the selections made previously.
       _pageSelectedSources = Set.from(initialSelection ?? []);
-      // Request initial sources from the BLoC
+
+      // 3. Trigger the page-specific BLoC (SourcesFilterBloc) to start
+      //    fetching the list of *all available* sources that the user can
+      //    potentially select from. The BLoC handles fetching, pagination,
+      //    loading states, and errors for the *list of options*.
       context.read<SourcesFilterBloc>().add(SourcesFilterRequested());
     });
+    // Add listener for pagination logic.
     _scrollController.addListener(_onScroll);
   }
 
@@ -88,6 +106,10 @@ class _SourceFilterPageState extends State<SourceFilterPage> {
             icon: const Icon(Icons.check),
             tooltip: l10n.headlinesFeedFilterApplyButton,
             onPressed: () {
+              // When the user taps 'Apply' (checkmark), pop the current route
+              // and return the final list of selected sources (`_pageSelectedSources`)
+              // from this page back to the previous page (`HeadlinesFilterPage`).
+              // `HeadlinesFilterPage` receives this list in its `onResult` callback.
               context.pop(_pageSelectedSources.toList());
             },
           ),
@@ -185,10 +207,14 @@ class _SourceFilterPageState extends State<SourceFilterPage> {
                   : null,
           value: isSelected,
           onChanged: (bool? value) {
+            // When a checkbox state changes, update the local selection set
+            // (`_pageSelectedSources`) for this page.
             setState(() {
               if (value == true) {
+                // Add the source if checked.
                 _pageSelectedSources.add(source);
               } else {
+                // Remove the source if unchecked.
                 _pageSelectedSources.remove(source);
               }
             });