[ECO-5468] Add Swift documentation for LiveObjects #2769

lawrence-forooghian · 2025-08-14T14:24:52Z

Description

Based on the Swift plugin at commit 714988d and ably-cocoa's integration/liveobjects branch at commit 5096ca3.

Some notes:

I haven't added Swift code to the batch API page because it's not yet implemented in Swift and the stub public API that we do have is incorrect and will be removed pre-v0.1 launch.
I haven't bothered adding Swift to the inband-objects page given that on the same page we're telling people to use the Swift SDK.

The quickstart content is a copy and paste of the JS quickstart.

Resolves https://ably.atlassian.net/browse/ECO-5468.

Checklist

Commits have been rebased.
Linting has been run against the changed file(s).
The PR adheres to the writing style guide and contribution guide.

coderabbitai · 2025-08-14T14:25:00Z

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 @coderabbit review command.

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

✨ Finishing Touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch liveobjects-swift-documentation

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

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbit in a new review comment at the desired location with your query.
PR comments: Tag @coderabbit in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbit gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbit read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbit help to get the list of available commands.

Other keywords and placeholders

Add @coderabbit ignore or @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbit summary or @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbit or @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

lawrence-forooghian · 2025-08-21T12:27:25Z

Need to resolve conflicts with main

Done

m-hulbert · 2025-08-21T16:09:27Z

src/pages/docs/liveobjects/counter.mdx

+<If lang="swift">
+To remove a counter update listener from _inside_ the listener function, you can call `unsubscribe()` on the subscription response that is passed as the second argument to the listener function:
+
+```swift


This needs to be wrapped in <Code> tags.

Thanks, done

m-hulbert · 2025-08-21T16:10:30Z

src/pages/docs/liveobjects/map.mdx

+<If lang="swift">
+To remove a map update listener from _inside_ the listener function, you can call `unsubscribe()` on the subscription response that is passed as the second argument to the listener function:
+
+```swift


This needs to be wrapped in <Code> tags.

Thanks, done

m-hulbert · 2025-08-21T16:13:44Z

src/data/languages/languageData.ts

@@ -33,6 +33,7 @@ export default {
  },
  liveObjects: {
    javascript: '2.9',
+    swift: '0.1',


It's a little odd that we're tying JS/Java to their Pub/Sub version but having Swift at 0.1 just because of how they're imported (just a comment).

The difference is that in JS and Java, the LiveObjects plugin is part of the core SDK and hence must have the same version. In Swift, we are forced to have a separate repository for the plugin, which has the happy side effect of allowing us to choose a semantic version number that reflects the fact that the LiveObjects API is experimental (JS and Java instead have to rely on code comments that state this).

Yeah, I totally understand the reasoning. Just from an external perspective it makes it look like JS and Java are far more mature than the Swift implementation.

For sure — do you have any thoughts on what we could do to mitigate this?

I think it's something we need to look at holistically that we should include on some guidance for releasing plugins. Not worth blocking this from releasing right now.

m-hulbert · 2025-08-21T16:16:29Z

src/pages/docs/liveobjects/counter.mdx

 </Code>

 ## Update LiveCounter <a id="update"/>

-Update the counter value by calling `LiveCounter.increment()` or `LiveCounter.decrement()`. These operations are synchronized across all clients and trigger data subscription callbacks for the counter, including on the client making the request.
+Update the counter value by calling <If lang="javascript">`LiveCounter.increment()` or `LiveCounter.decrement()`</If><If lang="swift">`LiveCounter.increment(amount:)` or `LiveCounter.decrement(amount:)`</If>. These operations are synchronized across all clients and trigger data subscription callbacks for the counter, including on the client making the request.


I'd personally keep all these occurrences as LiveCounter.increment() since the usage is immediately below to save ending up with 10+ theoretical if statements, unless you think it's that important to keep in.

Could you please explain what you mean by "10+ theoretical if statements"? In Swift, the name of a method always includes its parameter labels and this is usually respected in documentation; I could omit them to keep things maintainable here but it might look a bit sloppy to people who are used to working in Swift.

With 10+ I was referring to if we were to implement LiveObjects in all SDKs and they all have slightly different signatures.

I have no issues at all with keeping it, if it's the common pattern for Swift. We should extend this to other products though in that case (e.g. Chat definitely doesn't follow this format for Swift which is what made me question the need here).

We should extend this to other products though in that case (e.g. Chat definitely doesn't follow this format for Swift which is what made me question the need here).

Agreed — created ably/ably-cocoa#2093 and ably/ably-chat-swift#351

sacOO7

one more file conflict

I'll be adding Swift documentation for LiveObjects shortly, thus giving us our second language. Mark indicated that we wish to have a per-language quickstart guide, consistent with the other getting started guides e.g. chat.

lawrence-forooghian · 2025-08-22T14:24:05Z

one more file conflict

Fixed

Based on Swift plugin at commit 714988d and ably-cocoa's integration/liveobjects branch at commit 5096ca3. Some notes: - I haven't added Swift code to the batch API page because it's not yet implemented in Swift and the stub public API that we do have is incorrect and will be removed pre-v0.1 launch. - I haven't bothered adding Swift to the inband-objects page given that on the same page we're telling people to use the Swift SDK. The quickstart content is a copy and paste of the JS quickstart.

lawrence-forooghian · 2025-08-22T14:58:36Z

@sacOO7 I've pushed again to incorporate #2775

m-hulbert · 2025-08-28T11:51:50Z

src/pages/docs/liveobjects/quickstart/swift.mdx

@@ -0,0 +1,201 @@
+---
+title: "Quickstart: LiveObjects in Swift"


Suggested change

title: "Quickstart: LiveObjects in Swift"

title: "Getting started: LiveObjects in Swift"

updated in the java doc PR to avoid conflicts #2771 (comment)

lawrence-forooghian changed the base branch from main to 2025-08-14-new-user-build-fixes August 14, 2025 14:25

lawrence-forooghian added the review-app Create a Heroku review app label Aug 14, 2025

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 14, 2025 14:33 Inactive

Base automatically changed from 2025-08-14-new-user-build-fixes to main August 14, 2025 14:43

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from 7319933 to d2dab34 Compare August 14, 2025 16:36

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 14, 2025 16:36 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from d2dab34 to b35ffea Compare August 15, 2025 10:55

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 15, 2025 10:56 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from b35ffea to 511a378 Compare August 15, 2025 16:15

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 15, 2025 16:15 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from 511a378 to 4def6fd Compare August 18, 2025 12:53

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 12:53 Inactive

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 13:45 Inactive

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 16:38 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from a1043d1 to 834e167 Compare August 18, 2025 17:48

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 17:49 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from 834e167 to c60f671 Compare August 18, 2025 17:50

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 17:50 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from c60f671 to ec22885 Compare August 18, 2025 19:01

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 19:01 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from ec22885 to 3810265 Compare August 18, 2025 19:05

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 19:05 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from 3810265 to e0d57d2 Compare August 18, 2025 19:32

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 19:32 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch 3 times, most recently from 627669c to 4e2bf5f Compare August 18, 2025 20:02

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 18, 2025 20:02 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from 4e2bf5f to d2f1f26 Compare August 18, 2025 20:15

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 21, 2025 12:17 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from 7185deb to 555a1d6 Compare August 21, 2025 14:05

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 21, 2025 14:05 Inactive

m-hulbert reviewed Aug 21, 2025

View reviewed changes

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from 555a1d6 to eaf311a Compare August 21, 2025 17:20

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 21, 2025 17:20 Inactive

sacOO7 reviewed Aug 22, 2025

View reviewed changes

This was referenced Aug 22, 2025

Check that ably.com/docs include parameter labels when talking about methods ably/ably-cocoa#2093

Open

Check that ably.com/docs include parameter labels when talking about methods ably/ably-chat-swift#351

Open

lawrence-forooghian added 2 commits August 22, 2025 11:23

Introduce per-language quickstarts for LiveObjects

5af23cf

I'll be adding Swift documentation for LiveObjects shortly, thus giving us our second language. Mark indicated that we wish to have a per-language quickstart guide, consistent with the other getting started guides e.g. chat.

Make some LiveObjects concepts code language-agnostic

3c7b77d

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from eaf311a to f0598c5 Compare August 22, 2025 14:23

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 22, 2025 14:24 Inactive

lawrence-forooghian force-pushed the liveobjects-swift-documentation branch from f0598c5 to 47e4dfd Compare August 22, 2025 14:58

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 22, 2025 14:58 Inactive

umair-ably approved these changes Aug 26, 2025

View reviewed changes

umair-ably removed the Do not merge When the PR is in progress do not merge label Aug 26, 2025

m-hulbert approved these changes Aug 27, 2025

View reviewed changes

Merge branch 'main' into liveobjects-swift-documentation

c36c390

ably-ci deployed to ably-docs-liveobjects-s-hey5rx August 27, 2025 12:47 View deployment

m-hulbert reviewed Aug 28, 2025

View reviewed changes

Merge branch 'main' into liveobjects-swift-documentation

0b906d8

ably-ci temporarily deployed to ably-docs-liveobjects-s-hey5rx August 28, 2025 12:42 Inactive

umair-ably enabled auto-merge August 28, 2025 12:42

umair-ably merged commit 1a651f8 into main Aug 28, 2025
6 checks passed

umair-ably deleted the liveobjects-swift-documentation branch August 28, 2025 12:49

		@@ -0,0 +1,201 @@
		---
		title: "Quickstart: LiveObjects in Swift"

	title: "Quickstart: LiveObjects in Swift"
	title: "Getting started: LiveObjects in Swift"

[ECO-5468] Add Swift documentation for LiveObjects #2769

[ECO-5468] Add Swift documentation for LiveObjects #2769

Uh oh!

Conversation

lawrence-forooghian commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Uh oh!

coderabbitai bot commented Aug 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Chat

Support

CodeRabbit Commands (Invoked using PR/Issue comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Status, Documentation and Community

Uh oh!

lawrence-forooghian commented Aug 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sacOO7 left a comment

Choose a reason for hiding this comment

Uh oh!

lawrence-forooghian commented Aug 22, 2025

Uh oh!

lawrence-forooghian commented Aug 22, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

lawrence-forooghian commented Aug 14, 2025 •

edited

Loading

coderabbitai bot commented Aug 14, 2025 •

edited

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)