added comments and refactored code

lib/services/api.dart

@@ -9,6 +9,7 @@ class Api {
   static const String _rootUrl =
       'https://environment.data.gov.uk/flood-monitoring';
 
+  /// Fetches all stationszt
   static Future<List<FloodStation>> fetchAllStations() async {
     List<FloodStation> stations = [];
     final response = await http.get(Uri.parse('$_rootUrl/id/stations'));
@@ -37,7 +38,6 @@ class Api {
 
   /// [limit] limits the number of entries that are requested from the API and [offset] returns the
   /// list starting from the specified number
-
   static Future<List<FloodStation>> fetchStationsByRange(
       int limit, int offset) async {
     List<FloodStation> stations = [];
@@ -52,6 +52,7 @@ class Api {
     return stations;
   }
 
+  /// Fetches all readings from the station with the specified [stationId] from the last 24h
   static Future<List<Reading>> fetchReadingsFromStation(
       String stationId) async {
     List<Reading> readings = [];

lib/services/flood_station_provider.dart

@@ -4,19 +4,20 @@ import '../model/flood_station.dart';
 import 'api.dart';
 
 class FloodStationProvider extends ChangeNotifier {
+  // since the getter and setter for the following two fields would be empty, they are publicly accessible
   FloodStation? selectedStation;
   bool filtered = false;
 
   List<FloodStation> _allStations = [];
   List<FloodStation> _filteredStations = [];
+  CancelableOperation? _filteredStationsFuture;
 
   List<FloodStation> get allStations => _allStations;
   List<FloodStation> get filteredStations => _filteredStations;
-
-  CancelableOperation? _filteredStationsFuture;
-
   CancelableOperation? get filteredStationsFuture => _filteredStationsFuture;
 
+  /// loads all stations in batches of 500 and notifies listeners with every loop except if [silent] = true
+  /// this has lower performance than loading them all at once an shouldn't be used
   Future loadAllStationsInBatches({silent = false}) {
     int offset = 0;
     return Future.doWhile(() async {
@@ -34,6 +35,7 @@ class FloodStationProvider extends ChangeNotifier {
     });
   }
 
+  /// loads all flood stations and notifies listeners when done
   Future loadAllStations({silent = false}) {
     return Api.fetchAllStations().then(
       (value) {
@@ -45,6 +47,7 @@ class FloodStationProvider extends ChangeNotifier {
     );
   }
 
+  /// loads all stations whose label contains [filter]
   Future loadFilteredStations(String filter, {silent = false}) {
     if (_filteredStationsFuture != null) {
       _filteredStationsFuture!.cancel();
@@ -61,6 +64,7 @@ class FloodStationProvider extends ChangeNotifier {
     return future;
   }
 
+  /// cancels loading of filtered results.
   void cancelFilterLoading() {
     if (_filteredStationsFuture != null) {
       _filteredStationsFuture!.cancel();

lib/services/overlay_service.dart

@@ -15,7 +15,7 @@ mixin OverlayService {
     final overlayState = Overlay.of(context);
     _overlayEntry = OverlayEntry(
       builder: (context) => Positioned(
-        bottom: 85,
+        bottom: 85, // Positioned above the NavigationBar
         left: 0,
         right: 0,
         child: Center(