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.

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

• 🔍 Trigger a full 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.}

---

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

[AndyTWF]

Does this need to be an entire section? At most I would have this as a single sentence, e.g. "Most chat applications will use newestFirst to display messages from newest to oldest"

[sacOO7]

This section is required to describe message ordering semantics and subscriber message delivery. Without this documentation, the LLM has repeatedly hallucinated, as referenced in https://ably.atlassian.net/browse/FTF-489

[AndyTWF]

Sure, we need the information - my question is does it have to be an entire section, or could it literally be a sentence at the end of the previous section?

So the previous section has a table and then a sentence describing things?

[m-hulbert]

Agree with Andy here - also:

The orderBy parameter determines both which messages are retrieved and their return order:

I think this is a little confusing and the emphasis shouldn't be on which

[splindsay-92]

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

[m-hulbert]

Agree with Andy here - also:

The orderBy parameter determines both which messages are retrieved and their return order:

I think this is a little confusing and the emphasis shouldn't be on which

[m-hulbert]

Rather than newestFirst order I think this would read better as:

"Messages are returned in order, from the most recent to the oldest."

We avoid people needing to know what the property does then (even if the name is somewhat obvious, admittedly).

[m-hulbert]

As per above: I don't think we need to mention or associate orderBy here as it implies someone would have had to read the whole page to understand this section. We can just say that they're always returned from most recent to oldest.