[EDX-282] Changed related to docstring, generate docs and CI workflow

.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

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.

lib/ably/auth.rb

@@ -5,24 +5,7 @@
 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 @@ def initialize(client, token_params, auth_options)
       @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 @@ def authorise(*args, &block)
       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 @@ def authorise(*args, &block)
     # @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 @@ def request_token(token_params = {}, auth_options = {})
       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+

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 @@ def initialize(attributes = {})
       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

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 @@ def self.ChannelDetails(attributes)
     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,23 +36,29 @@ def initialize(attrs)
       @attributes = IdiomaticRubyWrapper(attrs.clone)
     end
 
-    # The identifier of the channel (CHD2a)
+    # The identifier of the channel
+    #
+    # @spec CHD2a
     #
     # @return [String]
     #
     def channel_id
       attributes[:channel_id]
     end
 
-    # The identifier of the channel (CHD2a)
+    # The identifier of the channel
+    #
+    # @spec CHD2a
     #
     # @return [String]
     #
     def name
       attributes[:name]
     end
 
-    # The status of the channel (CHD2b)
+    # A {Ably::Models::ChannelStatus} object.
+    #
+    # @spec CHD2b
     #
     # @return [Ably::Models::ChannelStatus, nil]
     #

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 @@ def self.ChannelMetrics(attributes)
     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,47 +36,67 @@ def initialize(attrs)
       @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]
     #
     def connections
       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]
     #
     def presence_connections
       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]
     #
     def presence_members
       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]
     #
     def presence_subscribers
       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]
     #
     def publishers
       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]
     #

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 @@ def self.ChannelOccupancy(attributes)
     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 @@ def initialize(attrs)
       @attributes = IdiomaticRubyWrapper(attrs.clone)
     end
 
-    # Metrics object (CHO2a)
+    # A {Ably::Models::ChannelMetrics} object.
+    #
+    # @spec CHO2a
     #
     # @return [Ably::Models::ChannelMetrics, nil]
     #