Add doc comments to all public API

Author: jezsung

packages/flutter_query/analysis_options.yaml

@@ -2,6 +2,7 @@ include: package:flutter_lints/flutter.yaml
 
 linter:
   rules:
+    - public_member_api_docs
 
 analyzer:
   exclude:

packages/flutter_query/lib/src/core/default_mutation_options.dart

@@ -20,6 +20,7 @@ import 'utils.dart';
 /// );
 /// ```
 class DefaultMutationOptions {
+  /// Creates default mutation options.
   const DefaultMutationOptions({
     this.networkMode = NetworkMode.online,
     this.gcDuration = const GcDuration(minutes: 5),

packages/flutter_query/lib/src/core/default_query_options.dart

@@ -18,6 +18,7 @@ import 'utils.dart';
 /// );
 /// ```
 class DefaultQueryOptions {
+  /// Creates default query options.
   const DefaultQueryOptions({
     this.enabled = true,
     this.networkMode = NetworkMode.online,

packages/flutter_query/lib/src/core/infinite_query_function_context.dart

@@ -9,6 +9,7 @@ import 'utils.dart';
 /// Shares the fields with [QueryFunctionContext] and adds pagination-specific
 /// fields for fetching pages of data.
 final class InfiniteQueryFunctionContext<TPageParam> {
+  /// Creates an infinite query function context.
   const InfiniteQueryFunctionContext({
     required this.queryKey,
     required this.client,

packages/flutter_query/lib/src/core/infinite_query_observer.dart

@@ -2,11 +2,13 @@ part of 'query_observer.dart';
 
 /// Data structure for infinite queries containing pages and their params.
 class InfiniteData<TData, TPageParam> {
+  /// Creates an infinite data container with the given pages and page params.
   const InfiniteData(
     this.pages,
     this.pageParams,
   );
 
+  /// Creates an empty infinite data container with no pages.
   const InfiniteData.empty()
       : pages = const [],
         pageParams = const [];

packages/flutter_query/lib/src/core/infinite_query_options.dart

@@ -1,3 +1,5 @@
+import 'package:meta/meta.dart';
+
 import 'default_query_options.dart';
 import 'infinite_query_function_context.dart';
 import 'network_mode.dart';
@@ -33,7 +35,12 @@ typedef PrevPageParamBuilder<TData, TPageParam> = TPageParam? Function(
   InfiniteData<TData, TPageParam> data,
 );
 
+/// Options for configuring an infinite query.
+///
+/// Contains all configuration for fetching and caching paginated data,
+/// including the query function, page parameter handling, and refetch behavior.
 class InfiniteQueryOptions<TData, TError, TPageParam> {
+  /// Creates options for an infinite query.
   InfiniteQueryOptions(
     List<Object?> queryKey,
     this.queryFn, {
@@ -57,25 +64,64 @@ class InfiniteQueryOptions<TData, TError, TPageParam> {
     this.meta,
   }) : queryKey = QueryKey(queryKey);
 
+  /// The key that uniquely identifies this query.
   final QueryKey queryKey;
+
+  /// The function that fetches a page of data.
   final InfiniteQueryFn<TData, TPageParam> queryFn;
+
+  /// The page parameter for the first page.
   final TPageParam initialPageParam;
+
+  /// Derives the next page parameter from the current data.
   final NextPageParamBuilder<TData, TPageParam> nextPageParamBuilder;
+
+  /// Derives the previous page parameter from the current data.
   final PrevPageParamBuilder<TData, TPageParam>? prevPageParamBuilder;
+
+  /// The maximum number of pages to keep in memory.
   final int? maxPages;
+
+  /// Whether this query is enabled.
   final bool? enabled;
+
+  /// The network connectivity mode for this query.
   final NetworkMode? networkMode;
+
+  /// How long data is considered fresh before becoming stale.
   final StaleDuration? staleDuration;
+
+  /// How long unused data remains in cache before garbage collection.
   final GcDuration? gcDuration;
+
+  /// Placeholder data shown while the query is loading.
   final InfiniteData<TData, TPageParam>? placeholder;
+
+  /// Whether to refetch when an observer mounts.
   final RefetchOnMount? refetchOnMount;
+
+  /// Whether to refetch when the app resumes from background.
   final RefetchOnResume? refetchOnResume;
+
+  /// Whether to refetch when network connectivity is restored.
   final RefetchOnReconnect? refetchOnReconnect;
+
+  /// Interval at which to automatically refetch.
   final Duration? refetchInterval;
+
+  /// Retry behavior for failed fetches.
   final RetryResolver<TError>? retry;
+
+  /// Whether to retry a failed query when a new observer mounts.
   final bool? retryOnMount;
+
+  /// Initial data to populate the cache before the first fetch.
   final InfiniteData<TData, TPageParam>? seed;
+
+  /// The timestamp when the seed data was last updated.
   final DateTime? seedUpdatedAt;
+
+  /// Arbitrary metadata associated with this query.
   final Map<String, dynamic>? meta;
 
   @override
@@ -147,6 +193,7 @@ class InfiniteQueryOptions<TData, TError, TPageParam> {
       'meta: $meta)';
 }
 
+@internal
 extension InfiniteQueryOptionsExt<TData, TError, TPageParam>
     on InfiniteQueryOptions<TData, TError, TPageParam> {
   InfiniteQueryOptions<TData, TError, TPageParam> withDefaults(

packages/flutter_query/lib/src/core/infinite_query_result.dart

@@ -52,6 +52,7 @@ typedef FetchPreviousPage<TData, TError, TPageParam>
 /// - [TError]: The type of error that may occur during fetching.
 /// - [TPageParam]: The type of the page parameter used for pagination.
 class InfiniteQueryResult<TData, TError, TPageParam> {
+  /// Creates an infinite query result.
   const InfiniteQueryResult({
     required this.status,
     required this.fetchStatus,

packages/flutter_query/lib/src/core/mutation_cache.dart

@@ -6,6 +6,7 @@ import 'mutation_cache_event.dart';
 import 'mutation_state.dart';
 import 'subscribable.dart';
 
+@internal
 typedef MutationCacheListener = void Function(MutationCacheEvent event);
 
 @internal

packages/flutter_query/lib/src/core/mutation_cache_event.dart

@@ -1,44 +1,29 @@
+import 'package:meta/meta.dart';
+
 import 'mutation.dart';
 
-/// Events emitted by [MutationCache] when its contents change.
-///
-/// Use pattern matching to handle specific event types:
-/// ```dart
-/// mutationCache.subscribe((event) {
-///   switch (event) {
-///     case MutationAddedEvent(:final mutation):
-///       print('Mutation added: ${mutation.mutationKey}');
-///     case MutationUpdatedEvent(:final mutation):
-///       print('Mutation updated: ${mutation.mutationKey}');
-///     case MutationRemovedEvent(:final mutation):
-///       print('Mutation removed: ${mutation.mutationKey}');
-///   }
-/// });
-/// ```
+@internal
 sealed class MutationCacheEvent {
   const MutationCacheEvent();
 }
 
-/// Emitted when a mutation is added to the cache.
+@internal
 final class MutationAddedEvent extends MutationCacheEvent {
   const MutationAddedEvent(this.mutation);
 
-  /// The mutation that was added.
   final Mutation mutation;
 }
 
-/// Emitted when a mutation is removed from the cache.
+@internal
 final class MutationRemovedEvent extends MutationCacheEvent {
   const MutationRemovedEvent(this.mutation);
 
-  /// The mutation that was removed.
   final Mutation mutation;
 }
 
-/// Emitted when a mutation's state is updated.
+@internal
 final class MutationUpdatedEvent extends MutationCacheEvent {
   const MutationUpdatedEvent(this.mutation);
 
-  /// The mutation whose state was updated.
   final Mutation mutation;
 }

packages/flutter_query/lib/src/core/mutation_function_context.dart

@@ -7,6 +7,7 @@ import 'utils.dart';
 /// a mutation and its associated callbacks such as `onMutate`, `onSuccess`,
 /// `onError`, and `onSettled`.
 class MutationFunctionContext {
+  /// Creates a mutation function context.
   const MutationFunctionContext({
     required this.mutationKey,
     required this.client,