ably 1.2.2 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 254c6088b3e3ef0d8cd6d2837b4efc73c2c7c04d8b7d4c61d416f023a8933603
-  data.tar.gz: 91d7b17e533b41ede327696aff66dd97ea35d6f7cf2a9fee9fd467fa42e9041e
+  metadata.gz: 8c2ec62cdc84e7558147bdab0c6bf2cbb933d75b1298aafbdd78848c6ebf62b1
+  data.tar.gz: b7edf7e0643e1ff2ead0ec4af3aee1caf0863dab40d6b9e247dd0e1bcd56b0e6
 SHA512:
-  metadata.gz: 8d51a067f02691481cf9489f82334f9200ef9ae00d71c2639c26a8d0b8fa62fbd76921fafb114699d4bf0d8e0f0e46f865bb07411a4dc4d6197a7ffeb9ebd6be
-  data.tar.gz: a392f7f5ec08ab445aaad519e45dc841090950402516ef2bafe3863817af77536b85549701acfc52e4a171544b79a190b499b3f8d32552a9a08973bf60831c3d
+  metadata.gz: 77f961eaa1ecab40502a2b8a3ce193ab9448e5c3df675ee7212369a94252b314af55b54200f016317d48727d6df7a6526551a7e1090f8dfd4c56e6bc9e32a00a
+  data.tar.gz: 50df5abcdd20c6afc63c5ac71043fad7a07547c16c752356011cb0b0713666d429e79474190c346dfadb9d89afd4f774d8e9d899dc7bcf0e7a363dcf40af3a1b

data/.github/workflows/.rspec_parallel

@@ -0,0 +1,3 @@
+--format documentation
+--format RspecJunitFormatter
+--out junit/<%= ENV['TEST_ENV_NUMBER'] %>_<%= ENV['TEST_TYPE'] %>_<%= ENV['PROTOCOL'] %>_ruby-<%= ENV['RUBY_VERSION'] %>.junit

data/.github/workflows/check.yml

@@ -26,14 +26,25 @@ jobs:
           PARALLEL_TEST_PROCESSORS: 2
           RSPEC_RETRY: true
           PROTOCOL: ${{ matrix.protocol }}
-        run: bundle exec parallel_rspec --prefix-output-with-test-env-number -- --format documentation --format RspecJunitFormatter --out ${{ matrix.protocol }}-${{ matrix.type }}-ruby-${{ matrix.ruby }}.junit -- spec/${{ matrix.type }}
+          TEST_TYPE: ${{ matrix.type }}
+          RUBY_VERSION: ${{ matrix.ruby }}
+        run: |
+          cp .github/workflows/.rspec_parallel .rspec_parallel
+          mkdir junit
+          bundle exec parallel_rspec --prefix-output-with-test-env-number --first-is-1 -- spec/${{ matrix.type }}
+      - uses: actions/upload-artifact@v3
+        with:
+          path: |
+            junit/
+            coverage/
+          retention-days: 7
       - name: Upload test results
         if: always()
         uses: ably-labs/test-observability-action@main
         with:
           server-url: 'https://test-observability.herokuapp.com'
           server-auth: ${{ secrets.TEST_OBSERVABILITY_SERVER_AUTH_KEY }}
-          path: '.'
+          path: 'junit/'
       - uses: coverallsapp/github-action@1.1.3
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}

data/.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      deployments: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '2.7'
+          bundler-cache: true
+
+      - name: Build Documentation
+        run: |
+          bundle exec yard --readme INTRO.md --tag "spec:Specification"
+          ls -al doc/
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-region: eu-west-2
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-ably-ruby
+          role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
+
+      - name: Upload Documentation
+        uses: ably/sdk-upload-action@v1
+        with:
+          sourcePath: doc/
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          artifactName: docs

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Change Log
 
+## [v1.2.3](https://github.com/ably/ably-ruby/tree/v1.2.3)
+
+[Full Changelog](https://github.com/ably/ably-ruby/compare/v1.2.2...v1.2.3)
+
+**Implemented enhancements:**
+
+- Add full docstring coverage to public API [\#376](https://github.com/ably/ably-ruby/pull/376) ([lukaszsliwa](https://github.com/lukaszsliwa))
+
+**Fixed bugs:**
+
+- Incorrect ProtocolMessage\#connection\_details object \(overwrites original connection\_details send on CONNECTED state\) [\#377](https://github.com/ably/ably-ruby/issues/377)
+
+**Merged pull requests:**
+
+- fix: remove inbound message size validation [\#382](https://github.com/ably/ably-ruby/pull/382) ([owenpearson](https://github.com/owenpearson))
+- Changes related to docstring, generate docs and CI workflow [\#376](https://github.com/ably/ably-ruby/pull/376) ([lukaszsliwa](https://github.com/lukaszsliwa))
+- Fix doc comment: incorrect channel.state type [\#375](https://github.com/ably/ably-ruby/pull/375) ([lukaszsliwa](https://github.com/lukaszsliwa))
+
 ## [v1.2.2](https://github.com/ably/ably-ruby/tree/v1.2.2)
 
 [Full Changelog](https://github.com/ably/ably-ruby/compare/v1.2.1...v1.2.2)

data/INTRO.md

@@ -0,0 +1,14 @@
+# Ably `Ruby` Client Library SDK API Reference
+
+The `Ruby` Client Library SDK supports a realtime and a REST interface.
+
+The realtime interface enables a client to maintain a persistent connection to Ably and publish, subscribe and be present on channels.
+The REST interface is stateless and typically implemented server-side. It is used to make requests such as retrieving statistics,
+token authentication and publishing to a channel.
+
+**Note**: The `Ruby` Client Library SDK implements the realtime and REST interfaces as two separate libraries.
+
+The `Ruby` API references are generated from the [Ably `Ruby` Client Library SDK source code](https://github.com/ably/ably-ruby)
+using [`yard`](https://yardoc.org/). View the [Ably docs](http://ably.com/docs/) for conceptual information on using Ably
+and for client library API references split between the [realtime](http://ably.com/docs/api/realtime-sdk)
+and [REST](http://ably.com/docs/api/rest-sdk) interfaces.

data/lib/ably/auth.rb

@@ -5,24 +5,7 @@ require 'securerandom'
 require 'ably/rest/middleware/external_exceptions'
 
 module Ably
-  # Auth is responsible for authentication with {https://www.ably.com Ably} using basic or token authentication
-  #
-  # Find out more about Ably authentication at: https://www.ably.com/docs/general/authentication/
-  #
-  # @!attribute [r] client_id
-  #   @return [String] The provided client ID, used for identifying this client for presence purposes
-  # @!attribute [r] current_token_details
-  #   @return [Ably::Models::TokenDetails] Current {Ably::Models::TokenDetails} issued by this library or one of the provided callbacks used to authenticate requests
-  # @!attribute [r] key
-  #   @return [String] Complete API key containing both the key name and key secret, if present
-  # @!attribute [r] key_name
-  #   @return [String] Key name (public part of the API key), if present
-  # @!attribute [r] key_secret
-  #   @return [String] Key secret (private secure part of the API key), if present
-  # @!attribute [r] options
-  #   @return [Hash] Default {Ably::Auth} options configured for this client
-  # @!attribute [r] token_params
-  #   @return [Hash] Default token params used for token requests, see {#request_token}
+  # Creates Ably {Ably::Models::TokenRequest} objects and obtains Ably Tokens from Ably to subsequently issue to less trusted clients.
   #
   class Auth
     include Ably::Modules::Conversions
@@ -124,9 +107,13 @@ module Ably
       @token_params.freeze
     end
 
-    # Ensures valid auth credentials are present for the library instance. This may rely on an already-known and valid token, and will obtain a new token if necessary.
+    # Instructs the library to get a new token immediately. When using the realtime client, it upgrades the current
+    # realtime connection to use the new token, or if not connected, initiates a connection to Ably, once the new token
+    # has been obtained. Also stores any `token_params` and `auth_options` passed
+    # in as the new defaults, to be used for all subsequent implicit or explicit token requests. Any `token_params`
+    # and `auth_options` objects passed in entirely replace, as opposed to being merged with, the current client library saved values.
     #
-    # In the event that a new token request is made, the provided options are used.
+    # @spec RSA10
     #
     # @param [Hash, nil] token_params the token params used for future token requests. When nil, previously configured token params are used
     # @param [Hash, nil] auth_options the authentication options used for future token requests. When nil, previously configure authentication options are used
@@ -205,7 +192,13 @@ module Ably
       authorize(*args, &block)
     end
 
-    # Request a {Ably::Models::TokenDetails} which can be used to make authenticated token based requests
+    # Calls the requestToken REST API endpoint to obtain an Ably Token according to the specified `token_params` and `auth_options`.
+    # Both `token_params` and `auth_options` are optional. When omitted or null, the default token parameters and authentication
+    # options for the client library are used, as specified in the `client_options` when the client library was instantiated,
+    # or later updated with an explicit authorize request. Values passed in are used instead of, rather than being merged with, the default values.
+    # To understand why an Ably {Ably::Models::TokenRequest} may be issued to clients in favor of a token, see Token Authentication explained.
+    #
+    # @spec RSA8e
     #
     # @param [Hash] auth_options (see #create_token_request)
     # @option auth_options [String]  :auth_url      a URL to be used to GET or POST a set of token request params, to obtain a signed token request
@@ -217,7 +210,7 @@ module Ably
     # @param [Hash] token_params (see #create_token_request)
     # @option (see #create_token_request)
     #
-    # @return [Ably::Models::TokenDetails]
+    # @return [Ably::Models::TokenDetails] A {Ably::Models::TokenDetails} object. RSA16
     #
     # @example
     #    # simple token request using basic auth
@@ -273,7 +266,17 @@ module Ably
       send_token_request(token_request)
     end
 
-    # Creates and signs a token request that can then subsequently be used by any client to request a token
+    # Creates and signs an {Ably::Models::TokenRequest} based on the specified (or if none specified, the client
+    # library stored) `token_params` and `auth_options`. Note this can only be used when the API key value is available
+    # locally. Otherwise, the {Ably::Models::TokenRequest} must be obtained from the key owner. Use this to generate
+    # an {Ably::Models::TokenRequest} in order to implement an Ably Token request callback for use by other clients.
+    # Both `token_params` and `auth_options` are optional. When omitted or null, the default token parameters
+    # and authentication options for the client library are used, as specified in the `client_options` when the client
+    # library was instantiated, or later updated with an explicit authorize request. Values passed in are used instead
+    # of, rather than being merged with, the default values. To understand why an {Ably::Models::TokenRequest} may be
+    # issued to clients in favor of a token, see Token Authentication explained.
+    #
+    # @spec RSA9
     #
     # @param [Hash] token_params the token params used in the token request
     # @option token_params [String]  :client_id     A client ID to associate with this token. The generated token may be used to authenticate as this +client_id+

data/lib/ably/models/auth_details.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [AuthDetails]
+  #
   def self.AuthDetails(attributes)
     case attributes
     when AuthDetails
@@ -27,14 +28,16 @@ module Ably::Models
       self.attributes.freeze
     end
 
-    %w(access_token).each do |attribute|
-      define_method attribute do
-        attributes[attribute.to_sym]
-      end
+    # The authentication token string.
+    #
+    # @spec AD2
+    #
+    # @return [String]
+    #
+    def access_token
+      attributes[:access_token]
     end
 
-    # @!attribute [r] attributes
-    # @return [Hash] Access the token details Hash object ruby'fied to use symbolized keys
     def attributes
       @hash_object
     end

data/lib/ably/models/channel_details.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [ChannelDetails]
+  #
   def self.ChannelDetails(attributes)
     case attributes
     when ChannelDetails
@@ -13,14 +14,17 @@ module Ably::Models
     end
   end
 
-  # ChannelDetails is a type that represents information for a channel including channelId, name, status and occupancy (CHD1)
+  # Contains the details of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object
+  # such as its ID and {Ably::Models::ChannelStatus}.
   #
   class ChannelDetails
     extend Ably::Modules::Enum
     extend Forwardable
     include Ably::Modules::ModelCommon
 
-    # The attributes of ChannelDetails (CHD2)
+    # The attributes of ChannelDetails
+    #
+    # @spec CHD2
     #
     attr_reader :attributes
 
@@ -32,7 +36,9 @@ module Ably::Models
       @attributes = IdiomaticRubyWrapper(attrs.clone)
     end
 
-    # The identifier of the channel (CHD2a)
+    # The identifier of the channel
+    #
+    # @spec CHD2a
     #
     # @return [String]
     #
@@ -40,7 +46,9 @@ module Ably::Models
       attributes[:channel_id]
     end
 
-    # The identifier of the channel (CHD2a)
+    # The identifier of the channel
+    #
+    # @spec CHD2a
     #
     # @return [String]
     #
@@ -48,7 +56,9 @@ module Ably::Models
       attributes[:name]
     end
 
-    # The status of the channel (CHD2b)
+    # A {Ably::Models::ChannelStatus} object.
+    #
+    # @spec CHD2b
     #
     # @return [Ably::Models::ChannelStatus, nil]
     #

data/lib/ably/models/channel_metrics.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [ChannelMetrics]
+  #
   def self.ChannelMetrics(attributes)
     case attributes
     when ChannelMetrics
@@ -13,8 +14,10 @@ module Ably::Models
     end
   end
 
-  # ChannelMetrics is a type that contains the count of publishers and subscribers, connections and presenceConnections,
-  # presenceMembers and presenceSubscribers (CHM1)
+  # Contains the metrics associated with a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel},
+  # such as the number of publishers, subscribers and connections it has.
+  #
+  # @spec CHM1
   #
   class ChannelMetrics
     extend Ably::Modules::Enum
@@ -33,7 +36,9 @@ module Ably::Models
       @attributes = IdiomaticRubyWrapper(attrs.clone)
     end
 
-    # The total number of connections to the channel (CHM2a)
+    # The number of realtime connections attached to the channel.
+    #
+    # @spec CHM2a
     #
     # @return [Integer]
     #
@@ -41,7 +46,11 @@ module Ably::Models
       attributes[:connections]
     end
 
-    # The total number of presence connections to the channel (CHM2b)
+    # The number of realtime connections attached to the channel with permission to enter the presence set, regardless
+    # of whether or not they have entered it. This requires the presence capability and for a client to not have specified
+    # a {Ably::Models::ChannelOptions::MODES} flag that excludes {Ably::Models::ChannelOptions::MODES}#PRESENCE.
+    #
+    # @spec CHM2b
     #
     # @return [Integer]
     #
@@ -49,7 +58,9 @@ module Ably::Models
       attributes[:presence_connections]
     end
 
-    # The total number of presence members for the channel (CHM2c)
+    # The number of members in the presence set of the channel.
+    #
+    # @spec CHM2c
     #
     # @return [Integer]
     #
@@ -57,7 +68,11 @@ module Ably::Models
       attributes[:presence_members]
     end
 
-    # The total number of presence subscribers for the channel (CHM2d)
+    # The number of realtime attachments receiving presence messages on the channel. This requires the subscribe capability
+    # and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
+    # {Ably::Models::ChannelOptions::MODES}#PRESENCE_SUBSCRIBE.
+    #
+    # @spec CHM2d
     #
     # @return [Integer]
     #
@@ -65,7 +80,11 @@ module Ably::Models
       attributes[:presence_subscribers]
     end
 
-    # The total number of publishers to the channel (CHM2e)
+    # The number of realtime attachments permitted to publish messages to the channel. This requires the publish
+    # capability and for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
+    # {Ably::Models::ChannelOptions::MODES}#PUBLISH.
+    #
+    # @spec CHM2e
     #
     # @return [Integer]
     #
@@ -73,7 +92,11 @@ module Ably::Models
       attributes[:publishers]
     end
 
-    # The total number of subscribers to the channel (CHM2f)
+    # The number of realtime attachments receiving messages on the channel. This requires the subscribe capability and
+    # for a client to not have specified a {Ably::Models::ChannelOptions::MODES} flag that excludes
+    # {Ably::Models::ChannelOptions::MODES}#SUBSCRIBE.
+    #
+    # @spec CHM2f
     #
     # @return [Integer]
     #

data/lib/ably/models/channel_occupancy.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [ChannelOccupancy]
+  #
   def self.ChannelOccupancy(attributes)
     case attributes
     when ChannelOccupancy
@@ -13,14 +14,18 @@ module Ably::Models
     end
   end
 
-  # Type that contain channel metrics (CHO1)
+  # Contains the metrics of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object.
+  #
+  # @spec CHO1
   #
   class ChannelOccupancy
     extend Ably::Modules::Enum
     extend Forwardable
     include Ably::Modules::ModelCommon
 
-    # The attributes of ChannelOccupancy (CH02)
+    # The attributes of ChannelOccupancy.
+    #
+    # @spec CH02
     #
     attr_reader :attributes
 
@@ -32,7 +37,9 @@ module Ably::Models
       @attributes = IdiomaticRubyWrapper(attrs.clone)
     end
 
-    # Metrics object (CHO2a)
+    # A {Ably::Models::ChannelMetrics} object.
+    #
+    # @spec CHO2a
     #
     # @return [Ably::Models::ChannelMetrics, nil]
     #

data/lib/ably/models/channel_options.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [ChannelOptions]
+  #
   def self.ChannelOptions(attributes)
     case attributes
     when ChannelOptions
@@ -19,6 +20,15 @@ module Ably::Models
     extend Forwardable
     include Ably::Modules::ModelCommon
 
+    # Describes the possible flags used to configure client capabilities, using {Ably::Models::ChannelOptions::MODES}.
+    #
+    #   PRESENCE		          The client can enter the presence set.
+    #   PUBLISH		            The client can publish messages.
+    #   SUBSCRIBE		          The client can subscribe to messages.
+    #   PRESENCE_SUBSCRIBE		The client can receive presence messages.
+    #
+    # @spec TB2d
+    #
     MODES = ruby_enum('MODES',
       presence: 0,
       publish: 1,
@@ -33,6 +43,8 @@ module Ably::Models
     def_delegators :attributes, :fetch, :size, :empty?
     # Initialize a new ChannelOptions
     #
+    # @spec TB3
+    #
     # @option params [Hash] (TB2c) params (for realtime client libraries only) a  of key/value pairs
     # @option modes [Hash] modes (for realtime client libraries only) an array of ChannelMode
     # @option cipher [Hash,Ably::Models::CipherParams]   :cipher   A hash of options or a {Ably::Models::CipherParams} to configure the encryption. *:key* is required, all other options are optional.
@@ -45,23 +57,33 @@ module Ably::Models
       attributes.clone
     end
 
-    # @!attribute cipher
+    # Requests encryption for this channel when not null, and specifies encryption-related parameters (such as algorithm,
+    # chaining mode, key length and key). See an example.
+    #
+    # @spec RSL5a, TB2b
     #
     # @return [CipherParams]
+    #
     def cipher
       attributes[:cipher]
     end
 
-    # @!attribute params
+    # Channel Parameters that configure the behavior of the channel.
+    #
+    # @spec TB2c
     #
     # @return [Hash]
+    #
     def params
       attributes[:params].to_h
     end
 
-    # @!attribute modes
+    # An array of {Ably:Models:ChannelOptions::MODES} objects.
+    #
+    # @spec TB2d
     #
     # @return [Array<ChannelOptions::MODES>]
+    #
     def modes
       attributes[:modes]
     end
@@ -69,6 +91,7 @@ module Ably::Models
     # Converts modes to a bitfield that coresponds to ProtocolMessage#flags
     #
     # @return [Integer]
+    #
     def modes_to_flags
       modes.map { |mode| Ably::Models::ProtocolMessage::ATTACH_FLAGS_MAPPING[mode.to_sym] }.reduce(:|)
     end

data/lib/ably/models/channel_state_change.rb

@@ -1,15 +1,5 @@
 module Ably::Models
-  # ChannelStateChange is a class that is emitted by the {Ably::Realtime::Channel} object
-  # when a state change occurs
-  #
-  # @!attribute [r] current
-  #   @return [Connection::STATE] Current channel state
-  # @!attribute [r] previous
-  #   @return [Connection::STATE] Previous channel state
-  # @!attribute [r] reason
-  #   @return [Ably::Models::ErrorInfo] Object describing the reason for a state change when not initiated by the consumer of the client library
-  # @!attribute [r] resumed
-  #   @return [Boolean] True when a channel is resumed, false when continuity on the channel is no longer provided indicating that the developer is now responsible for recovering lost messages on this channel through other means, such as using the hisory API
+  # Contains state change information emitted by {Ably::Rest::Channel} and {Ably::Realtime::Channel} objects.
   #
   class ChannelStateChange
     include Ably::Modules::ModelCommon
@@ -31,12 +21,52 @@ module Ably::Models
       raise ArgumentError, e
     end
 
-    %w(current previous event reason).each do |attribute|
-      define_method attribute do
-        @hash_object[attribute.to_sym]
-      end
+    # The new current {Ably::Realtime::Channel::STATE}.
+    #
+    # @spec RTL2a, RTL2b
+    #
+    # @return [Ably::Realtime::Channel::STATE]
+    #
+    def current
+      @hash_object[:current]
+    end
+
+    # The previous state. For the {Ably::Realtime::Channel::EVENT}(:update) event, this is equal to the current {Ably::Realtime::Channel::STATE}.
+    #
+    # @spec RTL2a, RTL2b
+    #
+    # @return [Ably::Realtime::Channel::EVENT]
+    #
+    def previous
+      @hash_object[:previous]
+    end
+
+    # The event that triggered this {Ably::Realtime::Channel::STATE} change.
+    #
+    # @spec TH5
+    #
+    # @return [Ably::Realtime::Channel::STATE]
+    #
+    def event
+      @hash_object[:event]
+    end
+
+    # An {Ably::Models::ErrorInfo} object containing any information relating to the transition.
+    #
+    # @spec RTL2e, TH3
+    #
+    # @return [Ably::Models::ErrorInfo, nil]
+    #
+    def reason
+      @hash_object[:reason]
     end
 
+    # Indicates whether message continuity on this channel is preserved, see Nonfatal channel errors for more info.
+    #
+    # @spec RTL2f, TH4
+    #
+    # @return [Boolean]
+    #
     def resumed
       !!@hash_object[:resumed]
     end

data/lib/ably/models/channel_status.rb

@@ -4,6 +4,7 @@ module Ably::Models
   # @param attributes (see #initialize)
   #
   # @return [ChannelStatus]
+  #
   def self.ChannelStatus(attributes)
     case attributes
     when ChannelStatus
@@ -13,14 +14,19 @@ module Ably::Models
     end
   end
 
-  # ChannelStatus is a type that contains status and occupancy for a channel (CHS1)
+  # Contains the status of a {Ably::Models::Rest::Channel} or {Ably::Models::Realtime::Channel} object
+  # such as whether it is active and its {Ably::Models::ChannelOccupancy}.
+  #
+  # @spec CHS1
   #
   class ChannelStatus
     extend Ably::Modules::Enum
     extend Forwardable
     include Ably::Modules::ModelCommon
 
-    # The attributes of ChannelStatus (CHS2)
+    # The attributes of ChannelStatus
+    #
+    # @spec CHS2
     #
     attr_reader :attributes
 
@@ -32,7 +38,9 @@ module Ably::Models
       @attributes = IdiomaticRubyWrapper(attrs.clone)
     end
 
-    # Represents if the channel is active (CHS2a)
+    # If true, the channel is active, otherwise false.
+    #
+    # @spec CHS2a
     #
     # @return [Boolean]
     #
@@ -42,7 +50,9 @@ module Ably::Models
     alias_method :active?, :is_active
     alias_method :is_active?, :is_active
 
-    # Occupancy ChannelOccupancy – occupancy is an object containing the metrics for the channel (CHS2b)
+    # A {Ably::Models::ChannelOccupancy} object.
+    #
+    # @spec CHS2b
     #
     # @return [Ably::Models::ChannelOccupancy, nil]
     #