[ECO-5135] Updates the Chat docs to include code examples for chat-swift #2315

umair-ably · 2024-11-22T14:34:25Z

Description

Updates the Chat docs to include code examples for chat-swift

https://ably.atlassian.net/browse/ECO-5135

Review

/chat/setup?lang=swift
/chat/connect?lang=swift
/chat/rooms?lang=swift
/chat/rooms/messages?lang=swift
/chat/rooms/presence?lang=swift
/chat/rooms/occupancy?lang=swift
/chat/rooms/typing?lang=swift
/chat/rooms/reactions?lang=swift
/chat/rooms/history?lang=swift

coderabbitai · 2024-11-22T14:34:32Z

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.

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

❤️ 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.
- Generate unit testing code for this file.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai generate unit testing code for this file.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai 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:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and generate unit testing code.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @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

Documentation and Community

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.

…y, presence, occupancy, reactions and typings.

maratal

LGTM (f7ca60d)

m-hulbert

There's quite a few places where we can combine, reduce and tidy up the amount of text required by using spans instead of blangs. I haven't commented on them all, after identifying the pattern. We also seem to have rewritten all text to not mention listeners in Swift - is this deliberate?

m-hulbert · 2024-11-29T12:25:34Z

content/chat/connect.textile

@@ -63,12 +71,17 @@ blang[react].

 blang[javascript].

+blang[swift].


Suggested change

blang[swift].

blang[javascript,swift].

This can roll up into the JS one above.

m-hulbert · 2024-11-29T12:27:53Z

content/chat/connect.textile

@@ -24,6 +25,9 @@ A connection can have any of the following statuses:
 blang[javascript].
  Use the "@current@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.ConnectionStatus.html#current property to check which status a connection is currently in:

+blang[swift].


If it's only the link that will be different then I think it may be clearer to combine it into a single block, e.g.:

blang[javascript,swift]. Use the <span lang="javascript>"@current@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.ConnectionStatus.html#current</span><span lang="swift"></span> property to check which status a connection is currently in:

No, here the property name is also different (which is probably something that should be fixed fyi @AndyTWF @lawrence-forooghian @ttypic)

I spoke to Andy about this separately and it has been updated for JS in a separate PR (#2300).

That PR modifies the same lines, I guess it should be merged first before me to proceed with this.

m-hulbert · 2024-11-29T12:34:50Z

content/chat/connect.textile

 blang[javascript].
  Use the "@connection.status.onChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.ConnectionStatus.html#onChange method to register a listener for status change updates:

 blang[react].
  Listeners can also be registered to monitor the changes in connection status. Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a status change listener. Changing the value provided for a listener will cause the previously registered listener instance to stop receiving events. All messages will be received by exactly one listener.

+blang[swift].


I think this could also roll into the JS line above with spans for the link change.

However, if bufferingPolicy is required then instead I think this should be kept separate, but we should explicitly state it needs to be set (can this not be a default config?)

It's also connection.status.onChange vs connection.onStatusChange which I think also should be fixed in the SDK (not sure which one, looks like the status.onChange is more idiomatic).

connection.onStatusChange was the one agreed in the DR

m-hulbert · 2024-11-29T12:39:16Z

content/chat/connect.textile

@@ -101,6 +121,13 @@ blang[javascript].

 blang[react].

+blang[swift].
+  To stop the subscription from firing new status events, call its @finish()@ function:


I think this can use the same terminology as JS in terms of removing the listener. We can put them in the same block as the JS text and code with span tags then.

I think it's also something that can be narrowed down to using only one term in all SDKs. Now js uses off, kotlin unsubscribe and swift finish. WDYT @ttypic @lawrence-forooghian

m-hulbert · 2024-11-29T12:40:17Z

content/chat/connect.textile

@@ -112,6 +139,9 @@ blang[javascript].

 blang[react].
  Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a listener to be notified of, and handle, periods of discontinuity.
+
+blang[swift].


Does this materially change from the JS? Again, I think we could put this in the JS block with span tags on the method name.

And the method name itself can be the same @umair-ably @lawrence-forooghian

For ref, it's onDiscontinuity in JS

m-hulbert · 2024-11-29T12:53:08Z

content/chat/rooms/index.textile


 h3(#release). Release a room

 Releasing a room allows the underlying resources to be garbage collected or released.

 Releasing a room may be optional for many applications. If you have multiple transient rooms, such as in the case of a 1:1 support chat, then it is may be more beneficial.
+Once "@rooms.release()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.Rooms.html#release has been called, the room will be unusable and a new instance will need to be created using "@rooms.get()@":#create if you want to reuse it.


I think this just needed swift added to the blang, as it isn't relevant to React.

React is so different in every aspect, doesn't it make sense to have a different .textile file for it? @m-hulbert

Heh, we've had a few conversations around trying that. We did it for Pub/Sub but the info gets a bit lost when you use them.

m-hulbert · 2024-11-29T12:56:27Z

content/chat/rooms/index.textile

@@ -180,6 +209,9 @@ blang[javascript].
 blang[react].
  Use the @roomStatus@ property to view the current "@Room@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.Room.html status changes. The @roomError@ property is its associated error. Any hooks that take an optional listener have these properties available in their response, such as @useMessages@ or @useTyping@. It is more common that you will monitor the room status in the specific feature hooks rather than needing to use @useRoom@. These events are related to the room instance of the nearest "@ChatRoomProvider@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat_react.ChatRoomProvider.html. For example, with the @useMessages@ hook:

+blang[swift].


Same comment as for connection - we can merge this into the JS one.

m-hulbert · 2024-11-29T12:58:00Z

content/chat/rooms/index.textile

+blang[swift].
+  You can also create a subscribtion to the room status updates. An event will be emitted whenever the status of the room changes.


Does this need to be separate to the JS?

If we agree to mitigate the difference between "registering a listener" and "creating a subscribtion" then sure it can be merged together.

What do you recommend here @m-hulbert? Broadly, Swift and JS are doing the same thing - though in JS we tend to prefer the term listener, rather than subscription. Are the concepts close enough that we can just use the same term across the board?

I'd personally prefer we don't use different terms across the ecosystems, so its not confusing for users using both

For the majority of SDKs we refer to listeners still in Pub/Sub, hence me questioning the difference here. It doesn't appear unidiomatic to Swift to continue with that, and that would be my recommendation. But I wasn't sure if there was a reason we'd actively avoided it in this PR.

m-hulbert · 2024-11-29T13:02:32Z

content/chat/setup.textile

+
+  The SDK is distributed as a Swift Package and can be installed using Xcode or by adding it as a dependency in your package’s @Package.swift@.
+
+  Please note the version listed in the language dropdown selector on this page corresponds to the Ably Pub/Sub SDK version, and not the Chat SDK version. Information on the latest Chat SDK release can be found at "https://github.com/ably/ably-chat-swift":https://github.com/ably/ably-chat-swift.


This will be fixed within the next few weeks, so can be removed. It's not something we state in any other product or language currently.

m-hulbert · 2024-11-29T13:03:02Z

content/chat/setup.textile

+
+  To install the @ably-chat-swift@ package in your Xcode Project:
+    * Paste @https://github.com/ably/ably-chat-swift@ in the Swift Packages search box. ( Xcode project → Swift Packages.. . → @+@ button)
+    * Select the AblyChat SDK for your target.


Suggested change

* Select the AblyChat SDK for your target.

* Select the Ably Chat SDK for your target.

ttypic · 2024-11-29T14:01:02Z

content/chat/rooms/reactions.textile


 blang[react].
  Subscribe to room reactions with the "@useRoomReactions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/functions/chat_react.useRoomReactions.html hook. Supply an optional listener to receive the room reactions.
+
+blang[swift].
+  Subscribe to a room reactions by creating a subscription. Use the @occupancy.subscribe(bufferingPolicy: .unbounded)@ method in a room to receive reactions:


Should be reactions here instead of occupancy

AndyTWF · 2024-11-29T16:30:30Z

content/chat/connect.textile

@@ -24,6 +25,9 @@ A connection can have any of the following statuses:
 blang[javascript].
  Use the "@current@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.ConnectionStatus.html#current property to check which status a connection is currently in:

+blang[swift].
+  Use the "@status@":https://sdk.ably.com/builds/ably/#status property to check which status a connection is currently in:


This appears to be a dead link right now?

I'm going to insert links that will look like:

"@status()@":https://sdk.ably.com/builds/ably/ably-chat-swift/main/typedoc/interfaces/chat.Rooms.html#status

Which are also yet dead, but with a potential to go live as soon as swift docs generation PR merged (ably/ably-chat-swift#165)

AndyTWF · 2024-11-29T16:43:29Z

content/chat/connect.textile

 blang[javascript].
  Use the "@connection.status.onChange()@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.ConnectionStatus.html#onChange method to register a listener for status change updates:

 blang[react].
  Listeners can also be registered to monitor the changes in connection status. Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a status change listener. Changing the value provided for a listener will cause the previously registered listener instance to stop receiving events. All messages will be received by exactly one listener.

+blang[swift].


connection.onStatusChange was the one agreed in the DR

AndyTWF · 2024-11-29T16:45:49Z

content/chat/connect.textile

@@ -112,6 +139,9 @@ blang[javascript].

 blang[react].
  Any hooks that take an optional listener to monitor their events, such as typing indicator events in the @useTyping@ hook, can also register a listener to be notified of, and handle, periods of discontinuity.
+
+blang[swift].


For ref, it's onDiscontinuity in JS

AndyTWF · 2024-11-29T16:49:20Z

content/chat/rooms/history.textile

+blang[swift].
+  |_. Parameter |_. Description |
+  | start | Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned. |
+  | end | Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned. |
+  | orderBy | The direction in which to retrieve messages from; either @oldestFirst@ or @newestFirst@. |
+  | limit | Maximum number of messages to be retrieved, up to 1,000. |


This divergence hasn't yet had a DR and thus hasn't been incorporated into JS - it was sorta an informal Slack conversation.

I suggest we allow the lack of parity for now until we get a chance to update JS - shouldn't take long but I don't want to block this PR getting merged.

AndyTWF · 2024-11-29T16:51:00Z

content/chat/rooms/index.textile

@@ -62,8 +67,11 @@ blang[react].

 blang[javascript].

+blang[swift].
+
+When you create or retrieve a room using @rooms.get()@, you need to choose which additional chat features you want enabled for that room. This is configured by passing a "@RoomOptions@":https://sdk.ably.com/builds/ably/ably-chat-js/main/typedoc/interfaces/chat_js.RoomOptions.html object as the second argument. In addition to setting which features are enabled, @RoomOptions@ also configures the properties of the associated features, such as the timeout period for typing indicators.


Should we be referencing chat-js's type descriptions in Swift, though - as opposed to Swift's own?

AndyTWF · 2024-11-29T16:54:37Z

content/chat/rooms/index.textile

+blang[swift].
+  You can also create a subscribtion to the room status updates. An event will be emitted whenever the status of the room changes.


What do you recommend here @m-hulbert? Broadly, Swift and JS are doing the same thing - though in JS we tend to prefer the term listener, rather than subscription. Are the concepts close enough that we can just use the same term across the board?

I'd personally prefer we don't use different terms across the ecosystems, so its not confusing for users using both

AndyTWF · 2024-11-29T16:56:29Z

content/chat/rooms/messages.textile

@@ -97,6 +108,13 @@ blang[javascript].
 blang[react].
  When you unmount the component that is using the @useMessages@ hook, it will automatically handle unsubscribing any associated listeners registered to receive messages.

+blang[swift].
+  To cancel the room messages subscribtion, call the provided @finish()@ method:


General question, is finish idiomatic in Swift? In JS we preferred unsubscribe instead.

AndyTWF · 2024-11-29T16:57:32Z

content/chat/rooms/presence.textile

+  let isPresent = try await room.presence.isUserPresent(clientID: "clemons123")
+  ```
+
+blang[react].


Extra blangs here?

correct 9df13d7

maratal · 2024-12-01T23:33:33Z

content/chat/rooms/index.textile

@@ -84,29 +92,42 @@ blang[javascript].
  ```[javascript]
  const room = chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}});


Doesn't it duplicates L80 sample? @m-hulbert

…o avoid merge conflicts.

Updates the Chat setup page to include setup instructions for chat-swift

f7ca60d

ably-ci temporarily deployed to ably-docs-eco-5135-ababflcbot7 November 22, 2024 14:35 Inactive

jamienewcomb marked this pull request as ready for review November 25, 2024 08:51

jamienewcomb requested review from m-hulbert, maratal and ttypic November 25, 2024 08:51

maratal force-pushed the ECO-5135 branch from f38ee9e to 229a6ff Compare November 28, 2024 12:49

jamienewcomb requested a review from lawrence-forooghian November 28, 2024 13:08

m-hulbert temporarily deployed to ably-docs-eco-5135-ycjnlgbhbiv November 28, 2024 14:21 Inactive

Added swift texts and samples for connection, rooms, messages, histor…

0761952

…y, presence, occupancy, reactions and typings.

maratal force-pushed the ECO-5135 branch from 229a6ff to 0761952 Compare November 28, 2024 14:56

jamienewcomb changed the title ~~[ECO-5135] Updates the Chat setup page to include setup instructions for chat-swift~~ [ECO-5135] Updates the Chat docs to include code examples for chat-swift Nov 28, 2024

jamienewcomb requested a review from GregHolmes November 28, 2024 16:39

maratal approved these changes Nov 28, 2024

View reviewed changes

m-hulbert deployed to ably-docs-eco-5135-ycjnlgbhbiv November 29, 2024 09:05 View deployment

m-hulbert reviewed Nov 29, 2024

View reviewed changes

ttypic reviewed Nov 29, 2024

View reviewed changes

AndyTWF reviewed Nov 29, 2024

View reviewed changes

maratal reviewed Dec 1, 2024

View reviewed changes

maratal added 3 commits December 2, 2024 00:49

Addressed rooms feedback not touching lines from another PR (#2300) t…

8b6ada5

…o avoid merge conflicts.

Fixed presence and reactions.

9df13d7

Fixed setup page.

ea58a6b

		@@ -63,12 +71,17 @@ blang[react].

		blang[javascript].

		blang[swift].

		blang[swift].
		You can also create a subscribtion to the room status updates. An event will be emitted whenever the status of the room changes.


		The SDK is distributed as a Swift Package and can be installed using Xcode or by adding it as a dependency in your package’s @Package.swift@.

		Please note the version listed in the language dropdown selector on this page corresponds to the Ably Pub/Sub SDK version, and not the Chat SDK version. Information on the latest Chat SDK release can be found at "https://github.com/ably/ably-chat-swift":https://github.com/ably/ably-chat-swift.

	* Select the AblyChat SDK for your target.
	* Select the Ably Chat SDK for your target.

		@@ -84,29 +92,42 @@ blang[javascript].
		```[javascript]
		const room = chatClient.rooms.get('basketball-stream', {typing: {timeoutMs: 5000}});

[ECO-5135] Updates the Chat docs to include code examples for chat-swift #2315

Are you sure you want to change the base?

[ECO-5135] Updates the Chat docs to include code examples for chat-swift #2315

Conversation

umair-ably commented Nov 22, 2024 • edited by jamienewcomb Loading

Description

Review

coderabbitai bot commented Nov 22, 2024

Review skipped

Chat

CodeRabbit Commands (Invoked using PR comments)

Other keywords and placeholders

CodeRabbit Configuration File (.coderabbit.yaml)

Documentation and Community

maratal left a comment • edited Loading

Choose a reason for hiding this comment

m-hulbert left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

umair-ably commented Nov 22, 2024 •

edited by jamienewcomb

Loading

CodeRabbit Configuration File (`.coderabbit.yaml`)

maratal left a comment •

edited

Loading