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

lib/api/marianumcloud/talk/talk_api.dart

@@ -60,10 +60,9 @@ abstract class TalkApi<T extends ApiResponse?> extends ApiRequest {
 
     final status = data.statusCode;
     if (status < 200 || status >= 300) {
-      // Talk's OCS errors put the real reason in the response body (e.g.
-      // expired session, removed participant, malformed reply target).
-      // Include a trimmed preview so the in-app error dialog and logs
-      // surface the cause instead of just the bare status code.
+      // Talk's OCS errors carry the real reason in the body (expired session,
+      // removed participant, ...); include a trimmed preview so the dialog and
+      // logs surface the cause instead of just the bare status code.
       final body = data.body.replaceAll(RegExp(r'\s+'), ' ').trim();
       final preview = body.length > 500 ? '${body.substring(0, 500)}…' : body;
       final detail = body.isEmpty

lib/api/marianumcloud/webdav/queries/list_files/list_files.dart

@@ -17,9 +17,8 @@ class ListFiles extends WebdavApi<ListFilesParams> {
 
   ListFiles(this.params, {this.onRetry}) : super(params);
 
-  // The Nextcloud root listing is significantly slower than subdirectories on
-  // our instance, so it gets a much longer ceiling. Subfolders fall back to a
-  // tighter timeout to keep the UI responsive.
+  // The root listing is much slower than subdirectories on our instance, so it
+  // gets a longer timeout ceiling; subfolders stay tighter to keep the UI snappy.
   static const Duration _rootTimeout = Duration(minutes: 3);
   static const Duration _subfolderTimeout = Duration(seconds: 30);
 

lib/api/marianumcloud/webdav/queries/list_files/list_files_cache.dart

@@ -27,18 +27,12 @@ class ListFilesCache extends SimpleCache<ListFilesResponse> {
     start(_documentId(path));
   }
 
-  /// The Nextcloud root listing is significantly slower than subfolders on
-  /// our instance and frequently returns HTTP 500. Since its content rarely
-  /// changes, the root payload is cached for a full day so app-resume and
-  /// connectivity-change auto-refetch triggers do not re-hit the slow root
-  /// endpoint within the same day. To avoid a long wait on the very first
-  /// open of the Files page, `prefetchRootListing` (called from `main`)
-  /// kicks off an async warm-up fetch in the background while the user is
-  /// still on the launch screen / other modules. Subfolders keep the
-  /// previous "always refetch on visit" TTL because their content changes
-  /// more often. Explicit user refreshes (rename, delete, copy/move,
-  /// upload) bypass the TTL via the inherited [renew] flag or via
-  /// [invalidate].
+  /// The Nextcloud root listing is much slower than subfolders on our instance
+  /// and frequently returns HTTP 500, but its content rarely changes — so it is
+  /// cached for a full day to keep app-resume/connectivity auto-refetches off
+  /// the slow root endpoint. [prefetchRootListing] warms it up in the background
+  /// after login. Subfolders keep the "always refetch on visit" TTL; explicit
+  /// user refreshes bypass the TTL via the inherited [renew] flag or [invalidate].
   static int _cacheTimeFor(String path) {
     final stripped = path.replaceAll('/', '').trim();
     return stripped.isEmpty ? RequestCache.cacheDay : RequestCache.cacheNothing;