chat docs: update history.mdx for specific use-cases

[sacOO7]

• Fixes https://ably.atlassian.net/browse/FTF-489
• Added use-case section and default values for params

Summary by CodeRabbit

Documentation

• Clarified chat history retrieval parameters with documented defaults and behavior specifications
• Added detailed guidance on message ordering options and their effects on retrieval and display
• Explained differences between standard history retrieval and retrieval methods before subscribing
• Enhanced code examples across multiple supported programming languages

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 113d4ede-2953-40dd-a950-28a3ca783595

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

Walkthrough

This pull request updates documentation for message history retrieval functionality, adding explicit parameter defaults (start, end, orderBy, limit) and a new section explaining message ordering behavior (newestFirst vs oldestFirst) to clarify API semantics and reduce implementation confusion.

Changes

Cohort / File(s)	Summary
Documentation: Message History API Clarification src/pages/docs/chat/rooms/history.mdx	Added parameter defaults for history and historyBeforeSubscribe methods; introduced "Understanding message ordering" section with newestFirst/oldestFirst comparison table; added clarifying aside that orderBy unavailable for historyBeforeSubscribe; revised code examples across JS, Swift, Kotlin, Jetpack, React to reflect updated semantics

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

Poem

🐰 Defaults now clear, from first to last,
No more confusion from the past!
Messages ordered, newest first,
This rabbit's thirst for clarity—quenched! 📚✨

🚥 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 accurately reflects the main change: updating the history.mdx documentation to include specific use-cases, defaults, and ordering guidance for chat history retrieval.
Linked Issues check	✅ Passed	All coding objectives from FTF-489 are met: added explicit use-case section, defined default parameter values for history methods, clarified ordering behavior, and provided concrete guidance to prevent LLM hallucinations.
Out of Scope Changes check	✅ Passed	All changes are directly in scope—only the history.mdx documentation file was modified to address the linked issue requirements without introducing unrelated alterations.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch update/chat-history-doc

---

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.}

[sacOO7]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Fix all issues with AI agents

In `@src/pages/docs/chat/rooms/history.mdx`:
- Line 114: The Swift typedoc link contains an extra closing parenthesis; edit
the line referencing historyBeforeSubscribe(withParams:) and remove the trailing
")" from the URL in the If lang="swift" link so the URL matches the intended
typedoc link exactly (keep the displayed label
[`historyBeforeSubscribe(withParams:)`] and only correct the href).
- Line 111: Remove the incorrect inline link on the function name so
`historyBeforeSubscribe()` is plain text and add a separate, clearly worded link
to the ordering guidance (the "understanding-message-ordering" anchor) in the
surrounding sentence; specifically, edit the paragraph that currently contains
[`historyBeforeSubscribe()`](`#understanding-message-ordering`) to render
historyBeforeSubscribe() without a link and include a second sentence or clause
linking to the ordering guidance (e.g., "See the ordering guidance in the
understanding-message-ordering section") so the function name and the ordering
documentation are distinct.

[maratal]

Small suggestions

[splindsay-92]

I think there are still a few comments that need addressing, but everything else is fine for me.

[m-hulbert]

I've just put one small suggestion on the wording change and then LGTM