docs: improve package docs and pub score readiness

[medz]

Summary

• Expand the package description so pub.dev accepts the pubspec.yaml metadata.
• Add a runnable example/main.dart so pub.dev can render an Example tab.
• Restructure the README around common cookie tasks and the API to use for each one.
• Rewrite public API dartdoc in a Flutter SDK style with semantics, constraints, examples, and cross-API references.

Validation

• dart analyze
• dart test
• dart doc --output <tmp>
• dart pub global run pana <tmp copy>: 160/160, 80/80 documented API elements
• dart pub publish --dry-run: 0 warnings

No linked issue.

Summary by CodeRabbit

• Documentation
  • Restructured README with clearer guidance, API selection table, and dedicated sections for common cookie operations.
  • Expanded API documentation across all public modules with detailed behavior descriptions.
  • Added runnable example demonstrating end-to-end cookie parsing, serialization, and jar usage.
  • Updated package description to clarify HTTP cookie handling and jar capabilities.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5576b097-a08b-46e2-964c-0c01c8083b4a

📥 Commits

Reviewing files that changed from the base of the PR and between b3c685c and 0ba574d.

📒 Files selected for processing (9)

• README.md
• example/main.dart
• lib/ocookie.dart
• lib/src/cookie.dart
• lib/src/cookie_jar.dart
• lib/src/cookie_key.dart
• lib/src/stored_cookie.dart
• lib/src/types.dart
• pubspec.yaml

---

📝 Walkthrough

Walkthrough

The PR rewrites the README into a structured tutorial, adds DartDoc comments across all public API files (cookie.dart, cookie_jar.dart, stored_cookie.dart, cookie_key.dart, types.dart, ocookie.dart), introduces a runnable example/main.dart with assert-based verification, and updates the pubspec.yaml description. No functional code changes are made.

Changes

Documentation, DartDoc, and Example

Layer / File(s)	Summary
Package metadata and library entry point pubspec.yaml, lib/ocookie.dart	Updates the package description to mention HTTP and cookie jar primitives; adds a library; directive and file-level DartDoc to the main library entry point.
Cookie class and enum DartDoc lib/src/types.dart, lib/src/cookie.dart	Rewrites and expands DartDoc for CookiePriority, CookieSameSite, CookieNullableField, the Cookie class, all public fields, and all public methods/factories (validate, serialize, fromString, parse, splitSetCookie); documents value encoding/decoding types.
CookieJar, CookiePolicy, CookieStore, CookieKey, StoredCookie DartDoc lib/src/cookie_key.dart, lib/src/stored_cookie.dart, lib/src/cookie_jar.dart	Expands DartDoc for CookiePolicy, CookieStore, MemoryCookieStore, CookieJar (class, save, saveCookies, loadStored, load, header), CookieKey, and StoredCookie (class, fields, fromCookie, copyWith, isExpired, toRequestCookie).
README rewrite README.md	Replaces the old README with a structured guide: What-It-Covers overview, API-selection table, tutorial sections for request parsing, serialization with SameSite/Partitioned/Secure constraints, splitting, CookieJar usage, copyWith/clear, custom encoding, and a condensed API reference link.
Runnable example example/main.dart	Adds main() demonstrating end-to-end usage: parsing a Cookie header, constructing and serializing a Cookie with attributes, parsing from a raw string, and using CookieJar to save Set-Cookie values and generate an outgoing Cookie header, verified with assert checks.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• odroe/ocookie#10: This PR expands DartDoc on StoredCookie methods (fromCookie, copyWith, isExpired, toRequestCookie) that were originally introduced in that PR.
• odroe/ocookie#11: This PR documents CookieJar, CookiePolicy, and CookieStore, and adds a CookieJar usage example, directly extending the jar primitives introduced in that PR.

Poem

🐰 Hop, hop, the docs are here at last!
With DartDoc comments, questions are a blast.
The README guides from parse to jar,
An example runs and checks each star.
Now every cookie finds its way — how grand!
A well-lit API, just as I planned. 🍪

🚥 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 'docs: improve package docs and pub score readiness' directly and specifically describes the main objective of the pull request: improving documentation and pub.dev readiness.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/improve-package-docs

---

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 and usage tips.}