ably
Add `setOptions` to the list of channel methods in the api docs
Why isn't setOptions in the list of channel methods in the api docs? https://ably.com/documentation/realtime/channels#publish
It's described in https://ably.com/documentation/realtime/channels#modifying-options , just not listed in the actual methods list
Also, https://ably.com/documentation/realtime/channels#get should list the options parameter as optional, and note that get() shouldn't be used to modify the options of an existing channel, should use channel.setOptions instead
┆Issue is synchronized with this Jira Bug by Unito ┆Attachments: image-20221029-060232.png
Also see RSN3c where we document that setting channel options when getting a channel is to avoided:
Note that this is soft-deprecated and may be removed in a future release, so should not be implemented in new client libraries. The supported way to update a set of
ChannelOptionsisChannel#setOptions
Therefore, I wonder whether we should be promoting the use 'set on get' at all ... i.e. at 2.1 (a) Setting channel options we should not say there's two ways, instead pushing users to set options after channel creation. That is assuming I'm not missing anything in respect of the motivation for the addition of the 'pure channel options set' API. 🤔
yep, sounds good.
My motivation for adding that bit to RSN3c was pretty much that I dislike channels#get(name, options) because it feels like a functional API, but it doesn't work like one. Like: it seems intuitive that if you do
one = Channels.get('test', options_one)
two = Channels.get('test', options_two)
then you should get a one channel object that uses the first set of options and a two object that uses the second set. But what you actually get is two references to at same channel object, which uses options_two.
If setOptions is split off, it makes it a bit more obvious that this is not a functional API, and that Channels.get just returns references to a single underlying object, which can be modified with setOptions.
In passing I noticed that the 3.1 Example here uses channels.get, specifying channel options.
It also uses the word "modify" when it then goes on to illustration channel.setOptions which I think is potentially misleading.
➤ Tony Bedford commented:
As the page has been split, see: https://ably.com/docs/api/realtime-sdk/channels ( https://ably.com/docs/api/realtime-sdk/channels|smart-link ) for the API reference docs.
➤ Tony Bedford commented:
Note, it’s actually a Channels method, not Channel method.
➤ Tony Bedford commented:
Mark Monaghan - I think would be a good first bug to take a look at. It’s just adding a method to the API reference. This should be a good way of getting familiar with our processes. Thanks.