Add comments for clients (#468)

Yang-33 · web-flow · commit 0e395fb745c4 · 2025-04-07T13:23:03.000+09:00
This change adds comments for sdk users in code related to the client.

(1) The internal HTTP client is exposed, but this change adds caution
against using it. If a breaking change is made to this, the version will
be raised, ignoring semver.
(2) For the user-facing HTTP client, this change adds comments with
examples using YARD.

Comments on the class methods will be improved in a separate PR.
diff --git a/generator/src/main/resources/line-bot-sdk-ruby-generator/api.pebble b/generator/src/main/resources/line-bot-sdk-ruby-generator/api.pebble
@@ -13,6 +13,33 @@ module Line
     module V2
       module {{ packageName | camelize }}
         class Api{{ operations.classname.indexOf('Blob') != -1 ? 'Blob' : '' }}Client
+          # Initializes a new {Line::Bot::V2::{{ packageName | camelize }}::Api{{ operations.classname.indexOf('Blob') != -1 ? 'Blob' : '' }}Client} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to '{{endpoint(operations.classname)}}' if none is provided.
+          #   You can override this for testing or to use a mock server.
+            {%- if packageName == 'module_attach' %}
+          # @param channel_id [String] The channel ID for Basic authentication.
+          # @param channel_secret [String] The channel secret for Basic authentication.
+            {%- elseif packageName != 'channel_access_token' %}
+          # @param channel_access_token [String] The channel access token for authorization.
+            {%- endif %}
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::{{ packageName | camelize }}::Api{{ operations.classname.indexOf('Blob') != -1 ? 'Blob' : '' }}Client.new(
+            {%- if packageName == 'module_attach' %}
+          #     channel_id: "YOUR_CHANNEL_ID",
+          #     channel_secret: "YOUR_CHANNEL_SECRET",
+            {%- elseif packageName != 'channel_access_token' %}
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+            {%- endif %}
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil{% if packageName == 'channel_access_token' %}{% elseif packageName == 'module_attach' %}, channel_id:, channel_secret:{% else %}, channel_access_token:{% endif %}, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || '{{endpoint(operations.classname)}}'{% if packageName == 'channel_access_token' %}{% elseif packageName == 'module_attach' %},
diff --git a/lib/line/bot/v2/channel_access_token/api/channel_access_token_client.rb b/lib/line/bot/v2/channel_access_token/api/channel_access_token_client.rb
@@ -18,6 +18,21 @@ module Bot
     module V2
       module ChannelAccessToken
         class ApiClient
+          # Initializes a new {Line::Bot::V2::ChannelAccessToken::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::ChannelAccessToken::ApiClient.new(
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api.line.me',
diff --git a/lib/line/bot/v2/http_client.rb b/lib/line/bot/v2/http_client.rb
@@ -6,43 +6,60 @@
 module Line
   module Bot
     module V2
+      # This class is not intended for line-bot-sdk-ruby users. Breaking changes may occur; use at your own risk.
+
       class HttpClient
+        # Initializes a new HttpClient instance.
+        #
+        # @param base_url [String] The base URL for requests.
+        # @param http_headers [Hash] The default HTTP headers.
+        # @param http_options [Hash] The HTTP options (same as Net::HTTP options).
+        # https://docs.ruby-lang.org/en/3.4/Net/HTTP.html#method-i-options
+        #
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def initialize(base_url:, http_headers: {}, http_options: {})
           @base_url = base_url
           @http_headers = { 'User-Agent' => "LINE-BotSDK-Ruby/#{Line::Bot::V2::VERSION}" }.merge(http_headers)
           @http_options = http_options
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def get(path:, query_params: nil, headers: nil)
           request = build_request(Net::HTTP::Get, path, query_params, headers)
           perform_request(request)
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def post(path:, query_params: nil, body_params: nil, headers: nil)
           request = build_request(Net::HTTP::Post, path, query_params, headers, body_params)
           perform_request(request)
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def put(path:, query_params: nil, body_params: nil, headers: nil)
           request = build_request(Net::HTTP::Put, path, query_params, headers, body_params)
           perform_request(request)
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def delete(path:, query_params: nil, headers: nil)
           request = build_request(Net::HTTP::Delete, path, query_params, headers)
           perform_request(request)
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def post_form(path:, query_params: nil, form_params: nil, headers: nil)
           request = build_form_request(Net::HTTP::Post, path, query_params, form_params, headers)
           perform_request(request)
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def post_form_multipart(path:, query_params: nil, form_params: nil, headers: nil)
           request = build_multipart_request(Net::HTTP::Post::Multipart, path, query_params, form_params, headers)
           perform_request(request)
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def put_form_multipart(path:, query_params: nil, form_params: nil, headers: nil)
           request = build_multipart_request(Net::HTTP::Put::Multipart, path, query_params, form_params, headers)
           perform_request(request)
diff --git a/lib/line/bot/v2/insight/api/insight_client.rb b/lib/line/bot/v2/insight/api/insight_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module Insight
         class ApiClient
+          # Initializes a new {Line::Bot::V2::Insight::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::Insight::ApiClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api.line.me',
diff --git a/lib/line/bot/v2/liff/api/liff_client.rb b/lib/line/bot/v2/liff/api/liff_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module Liff
         class ApiClient
+          # Initializes a new {Line::Bot::V2::Liff::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::Liff::ApiClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api.line.me',
diff --git a/lib/line/bot/v2/manage_audience/api/manage_audience_blob_client.rb b/lib/line/bot/v2/manage_audience/api/manage_audience_blob_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module ManageAudience
         class ApiBlobClient
+          # Initializes a new {Line::Bot::V2::ManageAudience::ApiBlobClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api-data.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::ManageAudience::ApiBlobClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api-data.line.me',
diff --git a/lib/line/bot/v2/manage_audience/api/manage_audience_client.rb b/lib/line/bot/v2/manage_audience/api/manage_audience_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module ManageAudience
         class ApiClient
+          # Initializes a new {Line::Bot::V2::ManageAudience::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::ManageAudience::ApiClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api.line.me',
diff --git a/lib/line/bot/v2/messaging_api/api/messaging_api_blob_client.rb b/lib/line/bot/v2/messaging_api/api/messaging_api_blob_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module MessagingApi
         class ApiBlobClient
+          # Initializes a new {Line::Bot::V2::MessagingApi::ApiBlobClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api-data.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::MessagingApi::ApiBlobClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api-data.line.me',
diff --git a/lib/line/bot/v2/messaging_api/api/messaging_api_client.rb b/lib/line/bot/v2/messaging_api/api/messaging_api_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module MessagingApi
         class ApiClient
+          # Initializes a new {Line::Bot::V2::MessagingApi::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::MessagingApi::ApiClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api.line.me',
diff --git a/lib/line/bot/v2/module/api/line_module_client.rb b/lib/line/bot/v2/module/api/line_module_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module Module
         class ApiClient
+          # Initializes a new {Line::Bot::V2::Module::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::Module::ApiClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api.line.me',
diff --git a/lib/line/bot/v2/module_attach/api/line_module_attach_client.rb b/lib/line/bot/v2/module_attach/api/line_module_attach_client.rb
@@ -18,6 +18,25 @@ module Bot
     module V2
       module ModuleAttach
         class ApiClient
+          # Initializes a new {Line::Bot::V2::ModuleAttach::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://manager.line.biz' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_id [String] The channel ID for Basic authentication.
+          # @param channel_secret [String] The channel secret for Basic authentication.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::ModuleAttach::ApiClient.new(
+          #     channel_id: "YOUR_CHANNEL_ID",
+          #     channel_secret: "YOUR_CHANNEL_SECRET",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_id:, channel_secret:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://manager.line.biz',
diff --git a/lib/line/bot/v2/shop/api/shop_client.rb b/lib/line/bot/v2/shop/api/shop_client.rb
@@ -18,6 +18,23 @@ module Bot
     module V2
       module Shop
         class ApiClient
+          # Initializes a new {Line::Bot::V2::Shop::ApiClient} instance.
+          #
+          # @param base_url [String] The base URL for requests (optional).
+          #   Defaults to 'https://api.line.me' if none is provided.
+          #   You can override this for testing or to use a mock server.
+          # @param channel_access_token [String] The channel access token for authorization.
+          # @param http_options [Hash] HTTP options (same as Net::HTTP options).
+          #   See: https://docs.ruby-lang.org/en/3.4/Net/HTTP.html to understand the options.
+          #
+          # @example
+          #   @client ||= Line::Bot::V2::Shop::ApiClient.new(
+          #     channel_access_token: "YOUR_CHANNEL_ACCESS_TOKEN",
+          #     http_options: {
+          #       open_timeout: 5,
+          #       read_timeout: 5,
+          #     }
+          #   )
           def initialize(base_url: nil, channel_access_token:, http_options: {})
             @http_client = HttpClient.new(
               base_url: base_url || 'https://api.line.me',
diff --git a/lib/line/bot/v2/utils.rb b/lib/line/bot/v2/utils.rb
@@ -2,6 +2,7 @@ module Line
   module Bot
     module V2
       module Utils
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.deep_underscore(hash)
           hash.each_with_object({}) do |(key, value), result|
             # Convert key to string if it's a symbol, then apply the regex
@@ -17,6 +18,7 @@ def self.deep_underscore(hash)
           end
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.deep_symbolize(object)
           case object
           when Hash
@@ -31,6 +33,7 @@ def self.deep_symbolize(object)
           end
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.deep_to_hash(object)
           if object.is_a?(Array)
             object.map { |item| deep_to_hash(item) }
@@ -47,6 +50,7 @@ def self.deep_to_hash(object)
           end
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.deep_camelize(object)
           case object
           when Array
@@ -62,6 +66,7 @@ def self.deep_camelize(object)
           end
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.deep_compact(object)
           case object
           when Hash
@@ -76,6 +81,7 @@ def self.deep_compact(object)
           end
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.deep_convert_reserved_words(object)
           case object
           when Hash
@@ -94,12 +100,14 @@ def self.deep_convert_reserved_words(object)
           end
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.hash_to_struct(hash)
           struct_klass = Struct.new(*hash.keys.map(&:to_sym))
           struct_values = hash.map { |_k, v| v.is_a?(Hash) ? hash_to_struct(v) : v }
           struct_klass.new(*struct_values)
         end
 
+        # NOTE: line-bot-sdk-ruby users should not use this. Breaking changes may occur, so use at your own risk.
         def self.camelize(str)
           str.to_s.split('_').inject { |memo, word| memo + word.capitalize }
         end
