[DOCS] Autogenerated code + improvements in source code documentation.

.gitignore

@@ -4,4 +4,6 @@ Gemfile.lock
 .DS_Store
 tmp
 *.log
-.env
+.env
+doc
+.yardoc

README.md

@@ -89,12 +89,9 @@ The parameters are:
 | `tracer`           | `Logger`  | An instance of a Logger-compatible object to use as a tracer.                                                                      |
 | `serializer_class` | `Object`  | A specific serializer class to use to serialize JSON.                                                                              |
 | `headers`          | `Hash`    | Custom HTTP Request Headers                                                                                                        |
-
-
-
 ### Using the API
 
-See [APIs](https://github.com/elastic/elasticsearch-serverless-ruby/blob/main/docs/apis.md) for the full list of available endpoints.
+See [APIs](https://github.com/elastic/elasticsearch-serverless-ruby/blob/main/docs/apis.md) for the full list of available endpoints. Check [rubydoc](https://rubydoc.info/gems/elasticsearch-serverless/) for the API reference, or run `yardoc` in the root of the project if you've checked out the code. The API reference documentation will be generated in the `doc` folder.
 
 Once you've instantiated a client with your API key and Elasticsearch endpoint, you can start ingesting documents into Elasticsearch Service. You can use the **Bulk API** for this. This API allows you to index, update and delete several documents in one request. You call the `bulk` API on the client with a body parameter, an Array of hashes that define the action and a document. Here's an example of indexing some classic books into the `books` index:
 

lib/elasticsearch-serverless.rb

@@ -27,9 +27,9 @@ class Client
 
     # Initializes an Elasticsearch Serverless Client
     #
-    # @param :api_key [String] Base64 String, format used to authenticate with Elasticsearch
-    # @param :url [String] Elasticsearch endpoint
-    # @param :arguments [Hash] Other optional arguments.
+    # @param [String] api_key Base64 String, format used to authenticate with Elasticsearch
+    # @param [String] url Elasticsearch endpoint
+    # @param [Hash] arguments Other optional arguments.
     # @option arguments [Symbol] :adapter A specific adapter for Faraday (e.g. `:patron`)
     # @option arguments [Boolean] :log Use the default logger (disabled by default)
     # @option arguments [Object] :logger An instance of a Logger-compatible object

lib/elasticsearch-serverless/api/async_search/delete.rb

@@ -22,7 +22,10 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Deletes an async search by ID. If the search is still running, the search request will be cancelled. Otherwise, the saved search results are deleted.
+        # Deletes an async search by identifier.
+        # If the search is still running, the search request will be cancelled.
+        # Otherwise, the saved search results are deleted.
+        # If the Elasticsearch security features are enabled, the deletion of a specific async search is restricted to: the authenticated user that submitted the original search request; users that have the +cancel_task+ cluster privilege.
         #
         # @option arguments [String] :id A unique identifier for the async search. (*Required*)
         # @option arguments [Hash] :headers Custom HTTP headers

lib/elasticsearch-serverless/api/async_search/get.rb

@@ -22,7 +22,8 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Retrieves the results of a previously submitted async search request given its ID.
+        # Retrieves the results of a previously submitted async search request given its identifier.
+        # If the Elasticsearch security features are enabled, access to the results of a specific async search is restricted to the user or API key that submitted it.
         #
         # @option arguments [String] :id A unique identifier for the async search. (*Required*)
         # @option arguments [Time] :keep_alive Specifies how long the async search should be available in the cluster. When not specified, the +keep_alive+ set with the corresponding submit async request will be used. Otherwise, it is possible to override the value and extend the validity of the request. When this period expires, the search, if still running, is cancelled. If the search is completed, its saved results are deleted.

lib/elasticsearch-serverless/api/async_search/status.rb

@@ -22,7 +22,9 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Retrieves the status of a previously submitted async search request given its ID.
+        # Get async search status
+        # Retrieves the status of a previously submitted async search request given its identifier, without retrieving search results.
+        # If the Elasticsearch security features are enabled, use of this API is restricted to the +monitoring_user+ role.
         #
         # @option arguments [String] :id A unique identifier for the async search. (*Required*)
         # @option arguments [Hash] :headers Custom HTTP headers

lib/elasticsearch-serverless/api/async_search/submit.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module AsyncSearch
       module Actions
-        # Executes a search request asynchronously.
+        # Runs a search request asynchronously.
+        # When the primary sort of the results is an indexed field, shards get sorted based on minimum and maximum value that they hold for that field, hence partial results become available following the sort criteria that was requested.
+        # Warning: Async search does not support scroll nor search requests that only include the suggest section.
+        # By default, Elasticsearch doesn’t allow you to store an async search response larger than 10Mb and an attempt to do this results in an error.
+        # The maximum allowed size for a stored async search response can be set by changing the +search.max_async_search_response_size+ cluster level setting.
         #
         # @option arguments [String, Array] :index A comma-separated list of index names to search; use +_all+ or empty string to perform the operation on all indices
         # @option arguments [Time] :wait_for_completion_timeout Blocks and waits until the search is completed up to a certain timeout. When the async search completes within the timeout, the response won’t include the ID as the results are not stored in the cluster. Server default: 1s.

lib/elasticsearch-serverless/api/bulk.rb

@@ -21,7 +21,8 @@
 module ElasticsearchServerless
   module API
     module Actions
-      # Allows to perform multiple index/update/delete operations in a single request.
+      # Performs multiple indexing or delete operations in a single API call.
+      # This reduces overhead and can greatly increase indexing speed.
       #
       # @option arguments [String] :index Name of the data stream, index, or index alias to perform bulk actions on.
       # @option arguments [String] :pipeline ID of the pipeline to use to preprocess incoming documents. If the index has a default ingest pipeline specified, then setting the value to +_none+ disables the default ingest pipeline for this request. If a final pipeline is configured it will always run, regardless of the value of this parameter.

lib/elasticsearch-serverless/api/cat/aliases.rb

@@ -22,7 +22,9 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Shows information about currently configured aliases to indices including filter and routing infos.
+        # Retrieves the cluster’s index aliases, including filter and routing information.
+        # The API does not return data stream aliases.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or the Kibana console. They are not intended for use by applications. For application consumption, use the aliases API.
         #
         # @option arguments [String, Array<String>] :name A comma-separated list of aliases to retrieve. Supports wildcards (+*+).  To retrieve all aliases, omit this parameter or use +*+ or +_all+.
         # @option arguments [String, Array<String>] :expand_wildcards Whether to expand wildcard expression to concrete indices that are open, closed or both.

lib/elasticsearch-serverless/api/cat/component_templates.rb

@@ -22,7 +22,10 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Returns information about existing component_templates templates.
+        # Returns information about component templates in a cluster.
+        # Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+        # They are not intended for use by applications. For application consumption, use the get component template API.
         #
         # @option arguments [String] :name The name of the component template. Accepts wildcard expressions. If omitted, all component templates are returned.
         # @option arguments [String] :format Specifies the format to return the columnar data in, can be set to +text+, +json+, +cbor+, +yaml+, or +smile+. Server default: text.

lib/elasticsearch-serverless/api/cat/count.rb

@@ -22,7 +22,10 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Provides quick access to the document count of the entire cluster, or individual indices.
+        # Provides quick access to a document count for a data stream, an index, or an entire cluster.
+        # NOTE: The document count only includes live documents, not deleted documents which have not yet been removed by the merge process.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+        # They are not intended for use by applications. For application consumption, use the count API.
         #
         # @option arguments [String, Array] :index Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (+*+). To target all data streams and indices, omit this parameter or use +*+ or +_all+.
         # @option arguments [String] :format Specifies the format to return the columnar data in, can be set to +text+, +json+, +cbor+, +yaml+, or +smile+. Server default: text.

lib/elasticsearch-serverless/api/cat/indices.rb

@@ -22,7 +22,12 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Returns information about indices: number of primaries and replicas, document counts, disk size, ...
+        # Returns high-level information about indices in a cluster, including backing indices for data streams.
+        # IMPORTANT: cat APIs are only intended for human consumption using the command line or Kibana console.
+        # They are not intended for use by applications. For application consumption, use the get index API.
+        # Use the cat indices API to get the following information for each index in a cluster: shard count; document count; deleted document count; primary store size; total store size of all shards, including shard replicas.
+        # These metrics are retrieved directly from Lucene, which Elasticsearch uses internally to power indexing and search. As a result, all document counts include hidden nested documents.
+        # To get an accurate count of Elasticsearch documents, use the cat count or count APIs.
         #
         # @option arguments [String, Array] :index Comma-separated list of data streams, indices, and aliases used to limit the request. Supports wildcards (+*+). To target all data streams and indices, omit this parameter or use +*+ or +_all+.
         # @option arguments [String] :bytes The unit used to display byte values.

lib/elasticsearch-serverless/api/cat/ml_data_frame_analytics.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about data frame analytics jobs.
+        # Returns configuration and usage information about data frame analytics jobs.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get data frame analytics jobs statistics API.
         #
         # @option arguments [String] :id The ID of the data frame analytics to fetch
         # @option arguments [Boolean] :allow_no_match Whether to ignore if a wildcard expression matches no configs. (This includes +_all+ string or when no configs have been specified)

lib/elasticsearch-serverless/api/cat/ml_datafeeds.rb

@@ -22,7 +22,14 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about datafeeds.
+        # Returns configuration and usage information about datafeeds.
+        # This API returns a maximum of 10,000 datafeeds.
+        # If the Elasticsearch security features are enabled, you must have +monitor_ml+, +monitor+, +manage_ml+, or +manage+
+        # cluster privileges to use this API.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get datafeed statistics API.
         #
         # @option arguments [String] :datafeed_id A numerical character string that uniquely identifies the datafeed.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request:  * Contains wildcard expressions and there are no datafeeds that match. * Contains the +_all+ string or no identifiers and there are no matches. * Contains wildcard expressions and there are only partial matches.  If +true+, the API returns an empty datafeeds array when there are no matches and the subset of results when there are partial matches. If +false+, the API returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/cat/ml_jobs.rb

@@ -22,7 +22,14 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about anomaly detection jobs.
+        # Returns configuration and usage information for anomaly detection jobs.
+        # This API returns a maximum of 10,000 jobs.
+        # If the Elasticsearch security features are enabled, you must have +monitor_ml+,
+        # +monitor+, +manage_ml+, or +manage+ cluster privileges to use this API.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get anomaly detection job statistics API.
         #
         # @option arguments [String] :job_id Identifier for the anomaly detection job.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request:  * Contains wildcard expressions and there are no jobs that match. * Contains the +_all+ string or no identifiers and there are no matches. * Contains wildcard expressions and there are only partial matches.  If +true+, the API returns an empty jobs array when there are no matches and the subset of results when there are partial matches. If +false+, the API returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/cat/ml_trained_models.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about inference trained models.
+        # Returns configuration and usage information about inference trained models.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get trained models statistics API.
         #
         # @option arguments [String] :model_id A unique identifier for the trained model.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request: contains wildcard expressions and there are no models that match; contains the +_all+ string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If +true+, the API returns an empty array when there are no matches and the subset of results when there are partial matches. If +false+, the API returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/cat/transforms.rb

@@ -22,7 +22,11 @@ module ElasticsearchServerless
   module API
     module Cat
       module Actions
-        # Gets configuration and usage information about transforms.
+        # Returns configuration and usage information about transforms.
+        #
+        # IMPORTANT: cat APIs are only intended for human consumption using the Kibana
+        # console or command line. They are not intended for use by applications. For
+        # application consumption, use the get transform statistics API.
         #
         # @option arguments [String] :transform_id A transform identifier or a wildcard expression. If you do not specify one of these options, the API returns information for all transforms.
         # @option arguments [Boolean] :allow_no_match Specifies what to do when the request: contains wildcard expressions and there are no transforms that match; contains the +_all+ string or no identifiers and there are no matches; contains wildcard expressions and there are only partial matches. If +true+, it returns an empty transforms array when there are no matches and the subset of results when there are partial matches. If +false+, the request returns a 404 status code when there are no matches or only partial matches. Server default: true.

lib/elasticsearch-serverless/api/clear_scroll.rb

@@ -21,7 +21,7 @@
 module ElasticsearchServerless
   module API
     module Actions
-      # Explicitly clears the search context for a scroll.
+      # Clears the search context and results for a scrolling search.
       #
       # @option arguments [String, Array] :scroll_id Comma-separated list of scroll IDs to clear. To clear all scroll IDs, use +_all+.
       # @option arguments [Hash] :headers Custom HTTP headers

lib/elasticsearch-serverless/api/close_point_in_time.rb

@@ -21,7 +21,7 @@
 module ElasticsearchServerless
   module API
     module Actions
-      # Close a point in time
+      # Closes a point-in-time.
       #
       # @option arguments [Hash] :headers Custom HTTP headers
       # @option arguments [Hash] :body request body

lib/elasticsearch-serverless/api/cluster/delete_component_template.rb

@@ -22,7 +22,8 @@ module ElasticsearchServerless
   module API
     module Cluster
       module Actions
-        # Deletes a component template
+        # Deletes component templates.
+        # Component templates are building blocks for constructing index templates that specify index mappings, settings, and aliases.
         #
         # @option arguments [String, Array<String>] :name Comma-separated list or wildcard expression of component template names used to limit the request. (*Required*)
         # @option arguments [Time] :master_timeout Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error. Server default: 30s.

lib/elasticsearch-serverless/api/cluster/get_component_template.rb

@@ -22,7 +22,7 @@ module ElasticsearchServerless
   module API
     module Cluster
       module Actions
-        # Returns one or more component templates
+        # Retrieves information about component templates.
         #
         # @option arguments [String] :name Comma-separated list of component template names used to limit the request. Wildcard (+*+) expressions are supported.
         # @option arguments [Boolean] :flat_settings If +true+, returns settings in flat format.