Use proper references in comments, where possible

rolandgeider · rolandgeider · commit 5da7da90679e · 2026-06-19T10:57:27.000+02:00
diff --git a/analysis_options.yaml b/analysis_options.yaml
@@ -66,6 +66,7 @@ linter:
     camel_case_types: false
     cancel_subscriptions: true
     cast_nullable_to_non_nullable: false # to be changed
+    comment_references: true
     constant_identifier_names: false
     control_flow_in_finally: true
     deprecated_consistency: true
diff --git a/lib/helpers/locale.dart b/lib/helpers/locale.dart
@@ -36,8 +36,9 @@ Locale? resolveLocale(List<Locale>? locales, Iterable<Locale> supportedLocales)
 }
 
 /// Stable string encoding for a [Locale], matching the keys generated by
-/// Flutter's AppLocalizations (e.g. `pt_BR`, `zh_Hant`, `pl`). [scriptCode]
-/// takes precedence over [countryCode] so locales like `zh_Hant` round-trip
+/// Flutter's AppLocalizations (e.g. `pt_BR`, `zh_Hant`, `pl`).
+/// [Locale.scriptCode] takes precedence over [Locale.countryCode] so locales
+/// like `zh_Hant` round-trip
 /// distinctly from plain `zh`.
 String encodeLocale(Locale locale) {
   final script = locale.scriptCode;
diff --git a/lib/helpers/shared_preferences.dart b/lib/helpers/shared_preferences.dart
@@ -23,7 +23,7 @@ class PreferenceHelper {
   /// SharedPreferences is migrated to SharedPreferencesAsync. This migration
   /// only happens once, as checked by the migrationCompletedKey.
   ///
-  /// [migrationCompletedKey] is used to track if the migration has been
+  /// `migrationCompletedKey` is used to track if the migration has been
   /// completed.
   Future<void> migrationSupportFunctionForSharedPreferences() async {
     const SharedPreferencesOptions sharedPreferencesOptions = SharedPreferencesOptions();
diff --git a/lib/powersync/api_client.dart b/lib/powersync/api_client.dart
@@ -43,7 +43,7 @@ class ApiClient {
 
   /// Fetches a short-lived PowerSync JWT and its endpoint URL from the
   /// wger backend. The `Authorization` header for this request is set
-  /// by the underlying [AuthHttpClient] based on the current auth state.
+  /// by the underlying `AuthHttpClient` based on the current auth state.
   Future<Map<String, dynamic>> getPowersyncToken() async {
     final response = await _client.get(
       Uri.parse('$serverUrl/api/v2/powersync-token'),
diff --git a/lib/powersync/connector.dart b/lib/powersync/connector.dart
@@ -125,7 +125,7 @@ class DjangoConnector extends PowerSyncBackendConnector {
 
   /// Transform a record before sending it to the backend.
   ///
-  /// Note that PowerSync hands us [op.opData] as native SQLite primitives only
+  /// Note that PowerSync hands us `op.opData` as native SQLite primitives only
   /// (`null`, `int`, `double`, `String`, `Uint8List`).
   ///
   ///   * inject the row [id] (PowerSync stores it separately from the
diff --git a/lib/providers/auth_credential.dart b/lib/providers/auth_credential.dart
@@ -21,7 +21,7 @@ import 'package:wger/helpers/jwt.dart';
 
 part 'auth_credential.freezed.dart';
 
-/// Sealed credential carried inside [AuthState] for every authenticated
+/// Sealed credential carried inside `AuthState` for every authenticated
 /// caller. Branch via `switch` or `is` to access the variant-specific
 /// fields; the two getters below cover everything the HTTP layer needs.
 ///
diff --git a/lib/providers/auth_http_client.dart b/lib/providers/auth_http_client.dart
@@ -40,14 +40,14 @@ const refreshLeeway = Duration(seconds: 30);
 ///   within [refreshLeeway] of now.
 /// - On a 401 reply for a *replayable* [http.Request] body that was sent
 ///   with a JWT, refresh once and retry. If the retry also returns 401
-///   the session is treated as genuinely revoked: [onSessionExpired]
+///   the session is treated as genuinely revoked: `onSessionExpired`
 ///   runs (clear credentials + surface a snackbar) and a synthetic 401
 ///   is returned to the caller. Non-replayable bodies (multipart /
 ///   streamed) are not retried; the pre-emptive refresh in the happy
 ///   path is the primary safeguard.
 ///
 /// Wrapped behind [authenticatedHttpClientProvider] so consumers
-/// ([WgerBaseProvider], PowerSync's connector) get the auth handling for
+/// (`WgerBaseProvider`, PowerSync's connector) get the auth handling for
 /// free without needing to know about the migration state.
 class AuthHttpClient extends http.BaseClient {
   final http.Client _inner;
diff --git a/lib/providers/auth_notifier.dart b/lib/providers/auth_notifier.dart
@@ -402,7 +402,7 @@ class AuthNotifier extends _$AuthNotifier {
   }
 
   /// Re-runs the auto-login flow. Used by the recovery screens
-  /// ([ServerUnreachableScreen], [PowerSyncUnreachableScreen]) so the user
+  /// (`ServerUnreachableScreen`, `PowerSyncUnreachableScreen`) so the user
   /// can retry without restarting the app.
   Future<void> retryAutoLogin() async {
     state = const AsyncLoading();
@@ -857,7 +857,8 @@ class AuthNotifier extends _$AuthNotifier {
   }
 
   /// User-driven logout. Always wipes credentials; the local PowerSync data is
-  /// kept by default and only wiped when the user opts out ([keepDataOnLogout]).
+  /// kept by default and only wiped when the user opts out
+  /// ([AuthCredentialsStorage.keepDataOnLogout]).
   /// Keeping it lets the same user sign back in and resume the sync
   /// incrementally instead of re-downloading everything; the DB-owner marker is
   /// preserved so a *different* user signing in still triggers a wipe.
@@ -939,7 +940,7 @@ class AuthNotifier extends _$AuthNotifier {
   }
 
   /// Removes the local PowerSync data whether or not the DB has been built:
-  /// when the instance exists we use PowerSync's own [disconnectAndClear],
+  /// when the instance exists we use PowerSync's own `disconnectAndClear`,
   /// otherwise (cold start, before any data widget has built it) we delete
   /// the on-disk files directly so no data survives.
   ///
diff --git a/lib/providers/exercise_filter_state.dart b/lib/providers/exercise_filter_state.dart
@@ -23,8 +23,8 @@ import 'package:wger/models/exercises/exercise.dart';
 /// UI state for the exercise list screen: the current filter
 /// configuration plus the resulting [filteredExercises]. The raw
 /// equipment / categories lists are not kept here, consumers that
-/// need them should watch [exerciseEquipmentProvider] /
-/// [exerciseCategoriesProvider] directly.
+/// need them should watch `exerciseEquipmentProvider` /
+/// `exerciseCategoriesProvider` directly.
 class ExerciseFilterState {
   final List<Exercise> exercises;
   final List<Exercise> filteredExercises;
diff --git a/lib/providers/exercise_filters_notifier.dart b/lib/providers/exercise_filters_notifier.dart
@@ -29,7 +29,7 @@ part 'exercise_filters_notifier.g.dart';
 
 /// Holds the *UI-side* state for the exercises catalogue screen:
 /// search term, selected categories/equipment, and the resulting
-/// [filteredExercises] list.
+/// [ExerciseFilterState.filteredExercises] list.
 @Riverpod(keepAlive: true)
 class ExerciseListFiltersNotifier extends _$ExerciseListFiltersNotifier {
   final _logger = Logger('ExerciseListFiltersNotifier');
diff --git a/lib/providers/helpers.dart b/lib/providers/helpers.dart
@@ -21,7 +21,7 @@ import 'dart:async';
 import 'package:flutter_riverpod/flutter_riverpod.dart';
 import 'package:flutter_riverpod/misc.dart' show ProviderListenable;
 
-/// Awaits the first value of [provider] by explicitly subscribing via
+/// Awaits the first value of `provider` by explicitly subscribing via
 /// [Ref.listen]. Use this in notifier methods (outside of `build()`)
 /// instead of `ref.read(streamProvider.future)`, which can hang
 /// indefinitely if no other consumer is `ref.watch`-ing the provider:
diff --git a/lib/providers/network_provider.dart b/lib/providers/network_provider.dart
@@ -31,9 +31,9 @@ part 'network_provider.g.dart';
 
 /// Returns whether the wger backend is actually reachable.
 ///
-/// Given [probeUri] any HTTP response counts as reachable, only a
+/// Given `probeUri` any HTTP response counts as reachable, only a
 /// network-level error or timeout counts as offline. The request carries
-/// [userAgent] so the probe is identifiable in server logs. When [probeUri] is
+/// `userAgent` so the probe is identifiable in server logs. When `probeUri` is
 /// null (no server configured yet, e.g. on the login screen) it falls back to
 /// a DNS lookup so there is still a sane online/offline signal.
 ///
diff --git a/lib/providers/nutrition_repository.dart b/lib/providers/nutrition_repository.dart
@@ -53,7 +53,7 @@ class NutritionRepository {
   }
 
   /// Inserts a nutritional plan into the local Drift table. If [plan] has no
-  /// id, Drift mints one and writes it back to [plan.id] so the caller can
+  /// id, Drift mints one and writes it back to `plan.id` so the caller can
   /// reference it immediately (e.g. to add child meals in the same flow).
   Future<void> addPlanLocalDrift(NutritionalPlan plan) async {
     _logger.finer('Inserting local nutritional plan');
diff --git a/lib/providers/routines_notifier.dart b/lib/providers/routines_notifier.dart
@@ -208,7 +208,7 @@ class RoutinesRiverpod extends _$RoutinesRiverpod {
   }
 
   /// Re-runs hydration on the current state and re-emits it. Triggered by
-  /// [ref.listen] on the upstream reference-data providers (sessions,
+  /// `ref.listen` on the upstream reference-data providers (sessions,
   /// exercises, repetition/weight units).
   void _rehydrate() {
     final current = state.value;
diff --git a/lib/providers/wger_base.dart b/lib/providers/wger_base.dart
@@ -47,7 +47,7 @@ final wgerBaseProvider = Provider<WgerBaseProvider>((ref) {
 /// when no prefix has been detected yet.
 ///
 /// Returns `null` when the user is not logged in (no server URL) or
-/// when [path] is null/empty.
+/// when `path` is null/empty.
 final mediaUrlBuilderProvider = Provider<Uri? Function(String? path)>((ref) {
   final serverUrl = ref.watch(authProvider).asData?.value.serverUrl;
   final prefix = ref.watch(mediaUrlPrefixProvider).asData?.value;
diff --git a/lib/providers/workout_logs_repository.dart b/lib/providers/workout_logs_repository.dart
@@ -34,7 +34,7 @@ final workoutLogRepositoryProvider = Provider<WorkoutLogRepository>((ref) {
 });
 
 /// Write-side access to the local `workout_log` table. Reading logs happens
-/// through [WorkoutSessionRepository.watchAllDrift], which joins logs onto
+/// through `WorkoutSessionRepository.watchAllDrift`, which joins logs onto
 /// their parent session.
 class WorkoutLogRepository {
   final _logger = Logger('WorkoutLogRepository');
diff --git a/lib/providers/workout_session_repository.dart b/lib/providers/workout_session_repository.dart
@@ -100,7 +100,7 @@ class WorkoutSessionRepository {
     await stmt.write(session.toCompanion());
   }
 
-  /// Inserts the session locally; if [session.id] is null, Drift mints one
+  /// Inserts the session locally; if `session.id` is null, Drift mints one
   /// and writes it back so the caller can reference it immediately.
   Future<void> addLocalDrift(WorkoutSession session) async {
     _logger.finer('Adding local workout session entry ${session.date}');
diff --git a/lib/screens/update_server_screen.dart b/lib/screens/update_server_screen.dart
@@ -21,7 +21,7 @@ import 'package:wger/helpers/consts.dart';
 import 'package:wger/l10n/generated/app_localizations.dart';
 
 /// Screen shown when the connected server's version is below the minimum
-/// required by this build of the app. Mirrors [UpdateAppScreen] but surfaces
+/// required by this build of the app. Mirrors `UpdateAppScreen` but surfaces
 /// to the user that they need to ask their server administrator to upgrade,
 /// rather than updating the app itself.
 class UpdateServerScreen extends StatelessWidget {
diff --git a/lib/widgets/core/error.dart b/lib/widgets/core/error.dart
@@ -25,7 +25,7 @@ import 'package:wger/l10n/generated/app_localizations.dart';
 /// HTML pages scroll inside this box rather than blowing up the parent card.
 const double _kMaxErrorHeight = 280;
 
-/// Inline error indicator used by [AsyncValueWidget]
+/// Inline error indicator used by `AsyncValueWidget`
 ///
 /// Accepts the raw error object so we can introspect it - if it's a
 /// [WgerHttpException] with [ErrorType.html] (typical for Django's debug
diff --git a/test/fake_auth_environment.dart b/test/fake_auth_environment.dart
@@ -23,7 +23,7 @@ import 'package:shared_preferences_platform_interface/in_memory_shared_preferenc
 import 'package:shared_preferences_platform_interface/shared_preferences_async_platform_interface.dart';
 import 'package:wger/helpers/shared_preferences.dart';
 
-/// Installs the platform-channel fakes that [authProvider] needs during
+/// Installs the platform-channel fakes that `authProvider` needs during
 /// its eager `build()`. Any screen test that transitively subscribes
 /// to `authProvider` (most do, via `wgerBaseProvider`) must call this.
 ///
