DX-1211: RealtimeChannel interface docstrings

[umair-ably]

Stacked on #2242 (Auth docstrings, base DX-1211/auth-docstrings); review/merge that first. Rewrites the JSDoc on the RealtimeChannel public surface in ably.d.ts per docstringRules.md: terse folded prose that surfaces call-site prerequisites, side-effects, and failure modes (the DX-1211 silent-failure class), with an @see companion link to the canonical reference.

Scope

ably.d.ts only (+135/−29). 19 members rewritten, 2 deliberately left as-is.

Highlights

• subscribe() (DX-1211 core): documents the silent missing-subscribe-mode trap — the listener never fires, the SDK warn-logs rather than rejecting (or rejects with a hinted ErrorInfo under strictMode). On all four active overloads.
• params / errorReason: declared non-optional but actually undefined/null until first attach/error — now carry a guard-against-undefined/null caveat (parallel to modes).
• history(): non-code persistence channel-rule prerequisite; fixes a @param copy-paste bug ("presence members" → "messages").
• Message ops (getMessage/updateMessage/deleteMessage/appendMessage/getMessageVersions): async reject framing (not synchronous throw) + message-interactions channel-rule prerequisite.
• push: universal missing-plugin throw kept at the call site; presence/annotations left unchanged (bundled by the default build, so the throw is modular-only).

Validation

npm run docs (TypeDoc treatWarningsAsErrors), prettier --check, and eslint all pass. A clean TypeDoc build confirms every {@link} resolves and nothing became undocumented.

Reviewer notes

• @see anchors follow the kebab-case convention (matching the Auth PR) but are unverified — ably/docs #3400 isn't live yet and @see is not TypeDoc-validated.
• A secondary feature-page @see for the five message-interaction members was deliberately omitted pending a confirmed slug.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

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: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 6b4ff328-b5e2-4ce9-89cd-d7c96e901f65

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DX-1211/realtimechannel-docstrings

---

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