docs: fix inaccurate dartdoc comments across all packages

[spydon]

Summary

• Audited every /// dartdoc comment on public API across all packages (gotrue, postgrest, storage_client, realtime_client, functions_client, supabase, supabase_common, supabase_flutter, supabase_typegen, yet_another_json_isolate, supabase_lints).
• Fixed comments that no longer matched the current implementation: stale parameter references, wrong exception types, incorrect defaults, wrong method names, and code examples that would not compile or run correctly.
• No code logic was changed, only doc comment text.

Test plan

• dart format run across all touched packages, no changes needed
• dart analyze run on each touched package, no new issues introduced (pre-existing worktree package-resolution noise unrelated to these edits)

Summary by CodeRabbit

• Documentation
  • Clarified supported request bodies, regional routing, token expiration, MFA QR codes, and authentication behavior.
  • Improved guidance for database queries, filters, RPC calls, return options, and data conversion examples.
  • Documented Realtime messaging, unsubscribe results, heartbeat statuses, and retry examples.
  • Clarified storage bucket creation, headers, table loading, and content-type errors.
  • Updated initialization, deep-linking, client configuration, local storage, and platform information guidance.
  • Corrected outdated references, examples, terminology, and minor wording issues across the SDK.

[coderabbitai]

Warning

Review limit reached

@spydon, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 1 minute

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 16fd83c7-0608-49eb-a7ba-ecb7967b1c8e

📥 Commits

Reviewing files that changed from the base of the PR and between 47f5359 and 51ff360.

📒 Files selected for processing (6)

• packages/gotrue/lib/src/gotrue_client.dart
• packages/postgrest/lib/src/postgrest_query_builder.dart
• packages/postgrest/lib/src/postgrest_rpc_builder.dart
• packages/postgrest/lib/src/types.dart
• packages/realtime_client/lib/src/transformers.dart
• packages/supabase_flutter/lib/src/supabase.dart

📝 Walkthrough

Walkthrough

This PR corrects and expands public API documentation and examples across Supabase Flutter packages. It updates descriptions for request formats, authentication, queries, realtime behavior, storage APIs, client configuration, deep links, and isolate disposal. No runtime code changes are reported.

Changes

API documentation corrections

Layer / File(s)	Summary
Functions and Auth documentation packages/functions_client/..., packages/gotrue/...	Documents binary request and response formats, regional invocation parameters, RSA JWKS caching, complete MFA QR-code URLs, and token-based session expiration.
PostgREST API documentation packages/postgrest/...	Corrects converter direction, query-builder sequencing, range-filter examples, RPC behavior, and returning-option semantics.
Realtime documentation and examples packages/realtime_client/...	Updates WebSocket feature coverage, unsubscribe results, message references, heartbeat statuses, retry examples, and transformer examples.
Storage documentation packages/storage_client/...	Clarifies table loading, bucket creation, header propagation, and invalid content-type exceptions.
Supabase platform documentation packages/supabase/..., packages/supabase_common/..., packages/supabase_flutter/..., packages/yet_another_json_isolate/...	Updates client options, initialization, deep-link handling, client information, local storage, rate limiting, and isolate disposal documentation.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• supabase/supabase-flutter#1489: Both PRs update GoTrue-related APIs; this PR corrects documentation, while the related PR enforces PKCE configuration.
• supabase/supabase-flutter#1655: Both PRs update documentation for overlapping public APIs, with different formatting and semantic focuses.

Suggested reviewers: tr00d

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation-only corrections made across the packages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-dartdocs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/gotrue/lib/src/gotrue_client.dart`:
- Around line 1762-1764: Update the documentation near getClaims to state that
JWKS fetching and caching applies to non-HS JWTs only when the token includes a
kid; clarify that RSA tokens without kid use the getUser(token) fallback
instead.

In `@packages/postgrest/lib/src/postgrest_query_builder.dart`:
- Around line 7-13: Update the introductory documentation for
PostgrestQueryBuilder to include upsert() and count() alongside the existing
initial methods, preserving the guidance that each returns a filter builder;
alternatively, change the “Call one of” wording to “For example” if the list is
intentionally non-exhaustive.

In `@packages/postgrest/lib/src/postgrest_rpc_builder.dart`:
- Around line 33-38: Update the documentation comment for the RPC builder method
to describe calls to database functions rather than stored procedures. Document
that when get is true, params must be a Map and the target function must support
read-only execution, while preserving the existing optional-parameter and
read-only access descriptions.

In `@packages/realtime_client/lib/src/transformers.dart`:
- Around line 97-111: Update the `convertColumn` documentation examples to quote
the `name` and `type` map keys in every example, using valid Dart string-key
syntax while preserving the example values and behavior.

In `@packages/supabase_flutter/lib/src/supabase.dart`:
- Around line 84-86: Update the documentation for the debug option in
Supabase.initialize to state that logging is disabled by default during Flutter
tests, while explicitly setting debug to true still enables logging. Keep the
existing kDebugMode default description unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d2eed913-2902-4a18-94d1-0327b3e23eae

📥 Commits

Reviewing files that changed from the base of the PR and between a08b657 and 47f5359.

📒 Files selected for processing (26)

• packages/functions_client/lib/src/functions_client.dart
• packages/functions_client/lib/src/types.dart
• packages/gotrue/lib/src/gotrue_client.dart
• packages/gotrue/lib/src/types/mfa.dart
• packages/gotrue/lib/src/types/session.dart
• packages/postgrest/lib/src/postgrest_builder.dart
• packages/postgrest/lib/src/postgrest_filter_builder.dart
• packages/postgrest/lib/src/postgrest_query_builder.dart
• packages/postgrest/lib/src/postgrest_rpc_builder.dart
• packages/postgrest/lib/src/types.dart
• packages/realtime_client/lib/realtime_client.dart
• packages/realtime_client/lib/src/realtime_channel.dart
• packages/realtime_client/lib/src/realtime_client.dart
• packages/realtime_client/lib/src/retry_timer.dart
• packages/realtime_client/lib/src/transformers.dart
• packages/storage_client/lib/src/iceberg/iceberg_rest_catalog.dart
• packages/storage_client/lib/src/storage_bucket_api.dart
• packages/storage_client/lib/src/storage_client.dart
• packages/storage_client/lib/src/types.dart
• packages/supabase/lib/src/realtime_client_options.dart
• packages/supabase/lib/src/supabase_client.dart
• packages/supabase_common/lib/src/client_info.dart
• packages/supabase_flutter/lib/src/local_storage.dart
• packages/supabase_flutter/lib/src/supabase.dart
• packages/supabase_flutter/lib/src/supabase_auth.dart
• packages/yet_another_json_isolate/lib/src/_isolates_io.dart

💤 Files with no reviewable changes (1)

• packages/supabase_flutter/lib/src/local_storage.dart