refactored and condensed technical documentation and comments across the codebase to improve readability

lib/state/app/modules/files/bloc/files_bloc.dart

@@ -44,11 +44,9 @@ class FilesBloc
     await _query(path, renew: true);
   }
 
-  /// LoadableState.reFetch (used by the pull-to-refresh indicator and the
-  /// error-screen retry button) routes through here. The inherited retry()
-  /// goes via gatherData() which respects the cache TTL — for an explicit
-  /// user-initiated reload we must bypass it, otherwise the root listing
-  /// silently returns its day-old cached payload without hitting the server.
+  /// Pull-to-refresh and error-screen retry route through here. Unlike the
+  /// inherited retry() (via gatherData(), which respects the cache TTL), this
+  /// bypasses the TTL — otherwise the root listing returns its day-old cache.
   @override
   void retry() {
     unawaited(refresh());

lib/state/app/modules/files/data_provider/files_data_provider.dart

@@ -6,16 +6,13 @@ import '../../../../../api/marianumcloud/webdav/webdav_api.dart';
 import '../../../../../api/request_cache.dart';
 
 class FilesDataProvider {
-  /// Lists files at [path]. Cached payload is delivered via [onCacheData] as
-  /// soon as it is read from disk, so callers can render stale data while the
-  /// network call is still pending. The Future itself resolves once both the
-  /// cache lookup and the network attempt have settled, throwing if no payload
-  /// could be obtained at all.
+  /// Lists files at [path]. Cached payload is delivered via [onCacheData] the
+  /// moment it is read from disk so callers can render stale data while the
+  /// network call is pending; the Future resolves once both have settled,
+  /// throwing if no payload could be obtained at all.
   ///
-  /// Pass [renew] for explicit user-triggered reloads (pull-to-refresh, after
-  /// a rename / delete / move / upload). It bypasses the per-path TTL in
-  /// [ListFilesCache] so the root listing — which is otherwise cached for a
-  /// full day — still refetches when the user actively asks for it.
+  /// Pass [renew] for explicit user-triggered reloads to bypass the per-path
+  /// TTL in [ListFilesCache] (the root listing is otherwise cached for a day).
   Future<ListFilesResponse> listFiles(
     String path, {
     void Function(ListFilesResponse)? onCacheData,