chore: ensure doc strings for rbi method arguments

lib/openai/base_model.rb

@@ -876,8 +876,6 @@ def initialize(type_info, spec = {})
     end
   end
 
-  # @api private
-  #
   # @abstract
   #
   # @example
@@ -903,6 +901,8 @@ def known_fields
         @known_fields ||= (self < OpenAI::BaseModel ? superclass.known_fields.dup : {})
       end
 
+      # @api private
+      #
       # @return [Hash{Symbol=>Hash{Symbol=>Object}}]
       def fields
         known_fields.transform_values do |field|

lib/openai/base_page.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module OpenAI
-  # @api private
-  #
   # @abstract
   #
   # @example

lib/openai/base_stream.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module OpenAI
-  # @api private
-  #
   # @example
   # ```ruby
   # stream.for_each do |message|

lib/openai/stream.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 module OpenAI
-  # @api private
-  #
   # @example
   # ```ruby
   # stream.for_each do |message|

rbi/lib/openai/base_model.rbi

@@ -438,6 +438,7 @@ module OpenAI
       def known_fields
       end
 
+      # @api private
       sig do
         returns(T::Hash[Symbol, T.all(OpenAI::BaseModel::KnownFieldShape, {type: OpenAI::Converter::Input})])
       end

rbi/lib/openai/base_page.rbi

@@ -1,7 +1,6 @@
 # typed: strong
 
 module OpenAI
-  # @api private
   module BasePage
     abstract!
 

rbi/lib/openai/base_stream.rbi

@@ -1,7 +1,6 @@
 # typed: strong
 
 module OpenAI
-  # @api private
   module BaseStream
     Message = type_member(:in)
     Elem = type_member(:out)

rbi/lib/openai/client.rbi

@@ -98,10 +98,15 @@ module OpenAI
         .returns(T.attached_class)
     end
     def self.new(
+      # Override the default base URL for the API, e.g., `"https://api.example.com/v2/"`
       base_url: nil,
+      # Defaults to `ENV["OPENAI_API_KEY"]`
       api_key: ENV["OPENAI_API_KEY"],
+      # Defaults to `ENV["OPENAI_ORG_ID"]`
       organization: ENV["OPENAI_ORG_ID"],
+      # Defaults to `ENV["OPENAI_PROJECT_ID"]`
       project: ENV["OPENAI_PROJECT_ID"],
+      # Max number of retries to attempt after a failed retryable request.
       max_retries: DEFAULT_MAX_RETRIES,
       timeout: DEFAULT_TIMEOUT_IN_SECONDS,
       initial_retry_delay: DEFAULT_INITIAL_RETRY_DELAY,

rbi/lib/openai/resources/audio/speech.rbi

@@ -16,7 +16,25 @@ module OpenAI
           )
             .returns(T.anything)
         end
-        def create(input:, model:, voice:, response_format: nil, speed: nil, request_options: {})
+        def create(
+          # The text to generate audio for. The maximum length is 4096 characters.
+          input:,
+          # One of the available [TTS models](https://platform.openai.com/docs/models#tts):
+          #   `tts-1` or `tts-1-hd`
+          model:,
+          # The voice to use when generating the audio. Supported voices are `alloy`, `ash`,
+          #   `coral`, `echo`, `fable`, `onyx`, `nova`, `sage` and `shimmer`. Previews of the
+          #   voices are available in the
+          #   [Text to speech guide](https://platform.openai.com/docs/guides/text-to-speech#voice-options).
+          voice:,
+          # The format to audio in. Supported formats are `mp3`, `opus`, `aac`, `flac`,
+          #   `wav`, and `pcm`.
+          response_format: nil,
+          # The speed of the generated audio. Select a value from `0.25` to `4.0`. `1.0` is
+          #   the default.
+          speed: nil,
+          request_options: {}
+        )
         end
 
         sig { params(client: OpenAI::Client).returns(T.attached_class) }

rbi/lib/openai/resources/audio/transcriptions.rbi

@@ -19,12 +19,35 @@ module OpenAI
             .returns(T.any(OpenAI::Models::Audio::Transcription, OpenAI::Models::Audio::TranscriptionVerbose))
         end
         def create(
+          # The audio file object (not file name) to transcribe, in one of these formats:
+          #   flac, mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
           file:,
+          # ID of the model to use. Only `whisper-1` (which is powered by our open source
+          #   Whisper V2 model) is currently available.
           model:,
+          # The language of the input audio. Supplying the input language in
+          #   [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`)
+          #   format will improve accuracy and latency.
           language: nil,
+          # An optional text to guide the model's style or continue a previous audio
+          #   segment. The
+          #   [prompt](https://platform.openai.com/docs/guides/speech-to-text#prompting)
+          #   should match the audio language.
           prompt: nil,
+          # The format of the output, in one of these options: `json`, `text`, `srt`,
+          #   `verbose_json`, or `vtt`.
           response_format: nil,
+          # The sampling temperature, between 0 and 1. Higher values like 0.8 will make the
+          #   output more random, while lower values like 0.2 will make it more focused and
+          #   deterministic. If set to 0, the model will use
+          #   [log probability](https://en.wikipedia.org/wiki/Log_probability) to
+          #   automatically increase the temperature until certain thresholds are hit.
           temperature: nil,
+          # The timestamp granularities to populate for this transcription.
+          #   `response_format` must be set `verbose_json` to use timestamp granularities.
+          #   Either or both of these options are supported: `word`, or `segment`. Note: There
+          #   is no additional latency for segment timestamps, but generating word timestamps
+          #   incurs additional latency.
           timestamp_granularities: nil,
           request_options: {}
         )

rbi/lib/openai/resources/audio/translations.rbi

@@ -16,7 +16,29 @@ module OpenAI
           )
             .returns(T.any(OpenAI::Models::Audio::Translation, OpenAI::Models::Audio::TranslationVerbose))
         end
-        def create(file:, model:, prompt: nil, response_format: nil, temperature: nil, request_options: {})
+        def create(
+          # The audio file object (not file name) translate, in one of these formats: flac,
+          #   mp3, mp4, mpeg, mpga, m4a, ogg, wav, or webm.
+          file:,
+          # ID of the model to use. Only `whisper-1` (which is powered by our open source
+          #   Whisper V2 model) is currently available.
+          model:,
+          # An optional text to guide the model's style or continue a previous audio
+          #   segment. The
+          #   [prompt](https://platform.openai.com/docs/guides/speech-to-text#prompting)
+          #   should be in English.
+          prompt: nil,
+          # The format of the output, in one of these options: `json`, `text`, `srt`,
+          #   `verbose_json`, or `vtt`.
+          response_format: nil,
+          # The sampling temperature, between 0 and 1. Higher values like 0.8 will make the
+          #   output more random, while lower values like 0.2 will make it more focused and
+          #   deterministic. If set to 0, the model will use
+          #   [log probability](https://en.wikipedia.org/wiki/Log_probability) to
+          #   automatically increase the temperature until certain thresholds are hit.
+          temperature: nil,
+          request_options: {}
+        )
         end
 
         sig { params(client: OpenAI::Client).returns(T.attached_class) }

rbi/lib/openai/resources/batches.rbi

@@ -14,7 +14,34 @@ module OpenAI
         )
           .returns(OpenAI::Models::Batch)
       end
-      def create(completion_window:, endpoint:, input_file_id:, metadata: nil, request_options: {})
+      def create(
+        # The time frame within which the batch should be processed. Currently only `24h`
+        #   is supported.
+        completion_window:,
+        # The endpoint to be used for all requests in the batch. Currently
+        #   `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported.
+        #   Note that `/v1/embeddings` batches are also restricted to a maximum of 50,000
+        #   embedding inputs across all requests in the batch.
+        endpoint:,
+        # The ID of an uploaded file that contains requests for the new batch.
+        #
+        #   See [upload file](https://platform.openai.com/docs/api-reference/files/create)
+        #   for how to upload a file.
+        #
+        #   Your input file must be formatted as a
+        #   [JSONL file](https://platform.openai.com/docs/api-reference/batch/request-input),
+        #   and must be uploaded with the purpose `batch`. The file can contain up to 50,000
+        #   requests, and can be up to 200 MB in size.
+        input_file_id:,
+        # Set of 16 key-value pairs that can be attached to an object. This can be useful
+        #   for storing additional information about the object in a structured format, and
+        #   querying for objects via API or the dashboard.
+        #
+        #   Keys are strings with a maximum length of 64 characters. Values are strings with
+        #   a maximum length of 512 characters.
+        metadata: nil,
+        request_options: {}
+      )
       end
 
       # Retrieves a batch.
@@ -25,7 +52,11 @@ module OpenAI
         )
           .returns(OpenAI::Models::Batch)
       end
-      def retrieve(batch_id, request_options: {})
+      def retrieve(
+        # The ID of the batch to retrieve.
+        batch_id,
+        request_options: {}
+      )
       end
 
       # List your organization's batches.
@@ -37,7 +68,17 @@ module OpenAI
         )
           .returns(OpenAI::CursorPage[OpenAI::Models::Batch])
       end
-      def list(after: nil, limit: nil, request_options: {})
+      def list(
+        # A cursor for use in pagination. `after` is an object ID that defines your place
+        #   in the list. For instance, if you make a list request and receive 100 objects,
+        #   ending with obj_foo, your subsequent call can include after=obj_foo in order to
+        #   fetch the next page of the list.
+        after: nil,
+        # A limit on the number of objects to be returned. Limit can range between 1 and
+        #   100, and the default is 20.
+        limit: nil,
+        request_options: {}
+      )
       end
 
       # Cancels an in-progress batch. The batch will be in status `cancelling` for up to
@@ -50,7 +91,11 @@ module OpenAI
         )
           .returns(OpenAI::Models::Batch)
       end
-      def cancel(batch_id, request_options: {})
+      def cancel(
+        # The ID of the batch to cancel.
+        batch_id,
+        request_options: {}
+      )
       end
 
       sig { params(client: OpenAI::Client).returns(T.attached_class) }