rbs 2.0.0 → 2.1.0

data/stdlib/csv/0/csv.rbs

@@ -1,122 +1,1611 @@
-# This class provides a complete interface to CSV files and data. It offers
-# tools to enable you to read and write to and from Strings or IO objects, as
-# needed.
+# <!-- rdoc-file=lib/csv.rb -->
+# ## CSV
+# CSV (comma-separated variables) data is a text representation of a table:
+# *   A *row* *separator* delimits table rows. A common row separator is the
+#     newline character `"\n"`.
+# *   A *column* *separator* delimits fields in a row. A common column separator
+#     is the comma character `","`.
 #
-# The most generic interface of the library is:
 #
-#     csv = CSV.new(string_or_io, **options)
+# This CSV String, with row separator `"\n"` and column separator `","`, has
+# three rows and two columns:
+#     "foo,0\nbar,1\nbaz,2\n"
 #
-#     # Reading: IO object should be open for read
-#     csv.read # => array of rows
-#     # or
-#     csv.each do |row|
-#       # ...
+# Despite the name CSV, a CSV representation can use different separators.
+#
+# For more about tables, see the Wikipedia article "[Table
+# (information)](https://en.wikipedia.org/wiki/Table_(information))", especially
+# its section "[Simple
+# table](https://en.wikipedia.org/wiki/Table_(information)#Simple_table)"
+#
+# ## Class CSV
+#
+# Class CSV provides methods for:
+# *   Parsing CSV data from a String object, a File (via its file path), or an
+#     IO object.
+# *   Generating CSV data to a String object.
+#
+#
+# To make CSV available:
+#     require 'csv'
+#
+# All examples here assume that this has been done.
+#
+# ## Keeping It Simple
+#
+# A CSV object has dozens of instance methods that offer fine-grained control of
+# parsing and generating CSV data. For many needs, though, simpler approaches
+# will do.
+#
+# This section summarizes the singleton methods in CSV that allow you to parse
+# and generate without explicitly creating CSV objects. For details, follow the
+# links.
+#
+# ### Simple Parsing
+#
+# Parsing methods commonly return either of:
+# *   An Array of Arrays of Strings:
+#     *   The outer Array is the entire "table".
+#     *   Each inner Array is a row.
+#     *   Each String is a field.
+#
+# *   A CSV::Table object.  For details, see [\CSV with
+#     Headers](#class-CSV-label-CSV+with+Headers).
+#
+#
+# #### Parsing a String
+#
+# The input to be parsed can be a string:
+#     string = "foo,0\nbar,1\nbaz,2\n"
+#
+# Method CSV.parse returns the entire CSV data:
+#     CSV.parse(string) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Method CSV.parse_line returns only the first row:
+#     CSV.parse_line(string) # => ["foo", "0"]
+#
+# CSV extends class String with instance method String#parse_csv, which also
+# returns only the first row:
+#     string.parse_csv # => ["foo", "0"]
+#
+# #### Parsing Via a File Path
+#
+# The input to be parsed can be in a file:
+#     string = "foo,0\nbar,1\nbaz,2\n"
+#     path = 't.csv'
+#     File.write(path, string)
+#
+# Method CSV.read returns the entire CSV data:
+#     CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Method CSV.foreach iterates, passing each row to the given block:
+#     CSV.foreach(path) do |row|
+#       p row
 #     end
-#     # or
-#     row = csv.shift
 #
-#     # Writing: IO object should be open for write
-#     csv << row
+# Output:
+#     ["foo", "0"]
+#     ["bar", "1"]
+#     ["baz", "2"]
+#
+# Method CSV.table returns the entire CSV data as a CSV::Table object:
+#     CSV.table(path) # => #<CSV::Table mode:col_or_row row_count:3>
 #
-# There are several specialized class methods for one-statement reading or
-# writing, described in the Specialized Methods section.
+# #### Parsing from an Open IO Stream
 #
-# If a String is passed into ::new, it is internally wrapped into a StringIO
-# object.
+# The input to be parsed can be in an open IO stream:
 #
-# `options` can be used for specifying the particular CSV flavor (column
-# separators, row separators, value quoting and so on), and for data conversion,
-# see Data Conversion section for the description of the latter.
+# Method CSV.read returns the entire CSV data:
+#     File.open(path) do |file|
+#       CSV.read(file)
+#     end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
 #
-# ## Specialized Methods
+# As does method CSV.parse:
+#     File.open(path) do |file|
+#       CSV.parse(file)
+#     end # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
 #
-# ### Reading
+# Method CSV.parse_line returns only the first row:
+#     File.open(path) do |file|
+#      CSV.parse_line(file)
+#     end # => ["foo", "0"]
 #
-#     # From a file: all at once
-#     arr_of_rows = CSV.read("path/to/file.csv", **options)
-#     # iterator-style:
-#     CSV.foreach("path/to/file.csv", **options) do |row|
-#       # ...
+# Method CSV.foreach iterates, passing each row to the given block:
+#     File.open(path) do |file|
+#       CSV.foreach(file) do |row|
+#         p row
+#       end
 #     end
 #
-#     # From a string
-#     arr_of_rows = CSV.parse("CSV,data,String", **options)
-#     # or
-#     CSV.parse("CSV,data,String", **options) do |row|
-#       # ...
+# Output:
+#     ["foo", "0"]
+#     ["bar", "1"]
+#     ["baz", "2"]
+#
+# Method CSV.table returns the entire CSV data as a CSV::Table object:
+#     File.open(path) do |file|
+#       CSV.table(file)
+#     end # => #<CSV::Table mode:col_or_row row_count:3>
+#
+# ### Simple Generating
+#
+# Method CSV.generate returns a String; this example uses method CSV#<< to
+# append the rows that are to be generated:
+#     output_string = CSV.generate do |csv|
+#       csv << ['foo', 0]
+#       csv << ['bar', 1]
+#       csv << ['baz', 2]
 #     end
+#     output_string # => "foo,0\nbar,1\nbaz,2\n"
 #
-# ### Writing
+# Method CSV.generate_line returns a String containing the single row
+# constructed from an Array:
+#     CSV.generate_line(['foo', '0']) # => "foo,0\n"
 #
-#     # To a file
-#     CSV.open("path/to/file.csv", "wb") do |csv|
-#       csv << ["row", "of", "CSV", "data"]
-#       csv << ["another", "row"]
-#       # ...
+# CSV extends class Array with instance method `Array#to_csv`, which forms an
+# Array into a String:
+#     ['foo', '0'].to_csv # => "foo,0\n"
+#
+# ### "Filtering" CSV
+#
+# Method CSV.filter provides a Unix-style filter for CSV data. The input data is
+# processed to form the output data:
+#     in_string = "foo,0\nbar,1\nbaz,2\n"
+#     out_string = ''
+#     CSV.filter(in_string, out_string) do |row|
+#       row[0] = row[0].upcase
+#       row[1] *= 4
 #     end
+#     out_string # => "FOO,0000\nBAR,1111\nBAZ,2222\n"
+#
+# ## CSV Objects
+#
+# There are three ways to create a CSV object:
+# *   Method CSV.new returns a new CSV object.
+# *   Method CSV.instance returns a new or cached CSV object.
+# *   Method CSV() also returns a new or cached CSV object.
+#
+#
+# ### Instance Methods
+#
+# CSV has three groups of instance methods:
+# *   Its own internally defined instance methods.
+# *   Methods included by module Enumerable.
+# *   Methods delegated to class IO. See below.
+#
+#
+# #### Delegated Methods
+#
+# For convenience, a CSV object will delegate to many methods in class IO. (A
+# few have wrapper "guard code" in CSV.) You may call:
+# *   IO#binmode
+# *   #binmode?
+# *   IO#close
+# *   IO#close_read
+# *   IO#close_write
+# *   IO#closed?
+# *   #eof
+# *   #eof?
+# *   IO#external_encoding
+# *   IO#fcntl
+# *   IO#fileno
+# *   #flock
+# *   IO#flush
+# *   IO#fsync
+# *   IO#internal_encoding
+# *   #ioctl
+# *   IO#isatty
+# *   #path
+# *   IO#pid
+# *   IO#pos
+# *   IO#pos=
+# *   IO#reopen
+# *   #rewind
+# *   IO#seek
+# *   #stat
+# *   IO#string
+# *   IO#sync
+# *   IO#sync=
+# *   IO#tell
+# *   #to_i
+# *   #to_io
+# *   IO#truncate
+# *   IO#tty?
+#
+#
+# ### Options
+#
+# The default values for options are:
+#     DEFAULT_OPTIONS = {
+#       # For both parsing and generating.
+#       col_sep:            ",",
+#       row_sep:            :auto,
+#       quote_char:         '"',
+#       # For parsing.
+#       field_size_limit:   nil,
+#       converters:         nil,
+#       unconverted_fields: nil,
+#       headers:            false,
+#       return_headers:     false,
+#       header_converters:  nil,
+#       skip_blanks:        false,
+#       skip_lines:         nil,
+#       liberal_parsing:    false,
+#       nil_value:          nil,
+#       empty_value:        "",
+#       strip:              false,
+#       # For generating.
+#       write_headers:      nil,
+#       quote_empty:        true,
+#       force_quotes:       false,
+#       write_converters:   nil,
+#       write_nil_value:    nil,
+#       write_empty_value:  "",
+#     }
+#
+# #### Options for Parsing
+#
+# Options for parsing, described in detail below, include:
+# *   `row_sep`: Specifies the row separator; used to delimit rows.
+# *   `col_sep`: Specifies the column separator; used to delimit fields.
+# *   `quote_char`: Specifies the quote character; used to quote fields.
+# *   `field_size_limit`: Specifies the maximum field size allowed.
+# *   `converters`: Specifies the field converters to be used.
+# *   `unconverted_fields`: Specifies whether unconverted fields are to be
+#     available.
+# *   `headers`: Specifies whether data contains headers, or specifies the
+#     headers themselves.
+# *   `return_headers`: Specifies whether headers are to be returned.
+# *   `header_converters`: Specifies the header converters to be used.
+# *   `skip_blanks`: Specifies whether blanks lines are to be ignored.
+# *   `skip_lines`: Specifies how comments lines are to be recognized.
+# *   `strip`: Specifies whether leading and trailing whitespace are to be
+#     stripped from fields. This must be compatible with `col_sep`; if it is
+#     not, then an `ArgumentError` exception will be raised.
+# *   `liberal_parsing`: Specifies whether CSV should attempt to parse
+#     non-compliant data.
+# *   `nil_value`: Specifies the object that is to be substituted for each null
+#     (no-text) field.
+# *   `empty_value`: Specifies the object that is to be substituted for each
+#     empty field.
+#
+#
+# ###### Option `row_sep`
+#
+# Specifies the row separator, a String or the Symbol `:auto` (see below), to be
+# used for both parsing and generating.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:row_sep) # => :auto
 #
-#     # To a String
-#     csv_string = CSV.generate do |csv|
-#       csv << ["row", "of", "CSV", "data"]
-#       csv << ["another", "row"]
-#       # ...
+# ---
+#
+# When `row_sep` is a String, that String becomes the row separator. The String
+# will be transcoded into the data's Encoding before use.
+#
+# Using `"\n"`:
+#     row_sep = "\n"
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `|` (pipe):
+#     row_sep = '|'
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0|bar,1|baz,2|"
+#     ary = CSV.parse(str, row_sep: row_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `--` (two hyphens):
+#     row_sep = '--'
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0--bar,1--baz,2--"
+#     ary = CSV.parse(str, row_sep: row_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `''` (empty string):
+#     row_sep = ''
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0bar,1baz,2"
+#     ary = CSV.parse(str, row_sep: row_sep)
+#     ary # => [["foo", "0bar", "1baz", "2"]]
+#
+# ---
+#
+# When `row_sep` is the Symbol `:auto` (the default), generating uses `"\n"` as
+# the row separator:
+#     str = CSV.generate do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#
+# Parsing, on the other hand, invokes auto-discovery of the row separator.
+#
+# Auto-discovery reads ahead in the data looking for the next `\r\n`, `\n`, or
+# `\r` sequence. The sequence will be selected even if it occurs in a quoted
+# field, assuming that you would have the same line endings there.
+#
+# Example:
+#     str = CSV.generate do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# The default `$INPUT_RECORD_SEPARATOR` (`$/`) is used if any of the following
+# is true:
+# *   None of those sequences is found.
+# *   Data is `ARGF`, `STDIN`, `STDOUT`, or `STDERR`.
+# *   The stream is only available for output.
+#
+#
+# Obviously, discovery takes a little time. Set manually if speed is important.
+# Also note that IO objects should be opened in binary mode on Windows if this
+# feature will be used as the line-ending translation can cause problems with
+# resetting the document position to where it was before the read ahead.
+#
+# ---
+#
+# Raises an exception if the given value is not String-convertible:
+#     row_sep = BasicObject.new
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.generate(ary, row_sep: row_sep)
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.parse(str, row_sep: row_sep)
+#
+# ###### Option `col_sep`
+#
+# Specifies the String field separator to be used for both parsing and
+# generating. The String will be transcoded into the data's Encoding before use.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:col_sep) # => "," (comma)
+#
+# Using the default (comma):
+#     str = CSV.generate do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `:` (colon):
+#     col_sep = ':'
+#     str = CSV.generate(col_sep: col_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo:0\nbar:1\nbaz:2\n"
+#     ary = CSV.parse(str, col_sep: col_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `::` (two colons):
+#     col_sep = '::'
+#     str = CSV.generate(col_sep: col_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo::0\nbar::1\nbaz::2\n"
+#     ary = CSV.parse(str, col_sep: col_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `''` (empty string):
+#     col_sep = ''
+#     str = CSV.generate(col_sep: col_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo0\nbar1\nbaz2\n"
+#
+# ---
+#
+# Raises an exception if parsing with the empty String:
+#     col_sep = ''
+#     # Raises ArgumentError (:col_sep must be 1 or more characters: "")
+#     CSV.parse("foo0\nbar1\nbaz2\n", col_sep: col_sep)
+#
+# Raises an exception if the given value is not String-convertible:
+#     col_sep = BasicObject.new
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.generate(line, col_sep: col_sep)
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.parse(str, col_sep: col_sep)
+#
+# ###### Option `quote_char`
+#
+# Specifies the character (String of length 1) used used to quote fields in both
+# parsing and generating. This String will be transcoded into the data's
+# Encoding before use.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:quote_char) # => "\"" (double quote)
+#
+# This is useful for an application that incorrectly uses `'` (single-quote) to
+# quote fields, instead of the correct `"` (double-quote).
+#
+# Using the default (double quote):
+#     str = CSV.generate do |csv|
+#       csv << ['foo', 0]
+#       csv << ["'bar'", 1]
+#       csv << ['"baz"', 2]
+#     end
+#     str # => "foo,0\n'bar',1\n\"\"\"baz\"\"\",2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]
+#
+# Using `'` (single-quote):
+#     quote_char = "'"
+#     str = CSV.generate(quote_char: quote_char) do |csv|
+#       csv << ['foo', 0]
+#       csv << ["'bar'", 1]
+#       csv << ['"baz"', 2]
 #     end
+#     str # => "foo,0\n'''bar''',1\n\"baz\",2\n"
+#     ary = CSV.parse(str, quote_char: quote_char)
+#     ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]
+#
+# ---
+#
+# Raises an exception if the String length is greater than 1:
+#     # Raises ArgumentError (:quote_char has to be nil or a single character String)
+#     CSV.new('', quote_char: 'xx')
+#
+# Raises an exception if the value is not a String:
+#     # Raises ArgumentError (:quote_char has to be nil or a single character String)
+#     CSV.new('', quote_char: :foo)
+#
+# ###### Option `field_size_limit`
+#
+# Specifies the Integer field size limit.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:field_size_limit) # => nil
+#
+# This is a maximum size CSV will read ahead looking for the closing quote for a
+# field. (In truth, it reads to the first line ending beyond this size.) If a
+# quote cannot be found within the limit CSV will raise a MalformedCSVError,
+# assuming the data is faulty. You can use this limit to prevent what are
+# effectively DoS attacks on the parser. However, this limit can cause a
+# legitimate parse to fail; therefore the default value is `nil` (no limit).
+#
+# For the examples in this section:
+#     str = <<~EOT
+#       "a","b"
+#       "
+#       2345
+#       ",""
+#     EOT
+#     str # => "\"a\",\"b\"\n\"\n2345\n\",\"\"\n"
+#
+# Using the default `nil`:
+#     ary = CSV.parse(str)
+#     ary # => [["a", "b"], ["\n2345\n", ""]]
+#
+# Using `50`:
+#     field_size_limit = 50
+#     ary = CSV.parse(str, field_size_limit: field_size_limit)
+#     ary # => [["a", "b"], ["\n2345\n", ""]]
+#
+# ---
+#
+# Raises an exception if a field is too long:
+#     big_str = "123456789\n" * 1024
+#     # Raises CSV::MalformedCSVError (Field size exceeded in line 1.)
+#     CSV.parse('valid,fields,"' + big_str + '"', field_size_limit: 2048)
+#
+# ###### Option `converters`
+#
+# Specifies converters to be used in parsing fields. See [Field
+# Converters](#class-CSV-label-Field+Converters)
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:converters) # => nil
+#
+# The value may be a field converter name (see [Stored
+# Converters](#class-CSV-label-Stored+Converters)):
+#     str = '1,2,3'
+#     # Without a converter
+#     array = CSV.parse_line(str)
+#     array # => ["1", "2", "3"]
+#     # With built-in converter :integer
+#     array = CSV.parse_line(str, converters: :integer)
+#     array # => [1, 2, 3]
+#
+# The value may be a converter list (see [Converter
+# Lists](#class-CSV-label-Converter+Lists)):
+#     str = '1,3.14159'
+#     # Without converters
+#     array = CSV.parse_line(str)
+#     array # => ["1", "3.14159"]
+#     # With built-in converters
+#     array = CSV.parse_line(str, converters: [:integer, :float])
+#     array # => [1, 3.14159]
+#
+# The value may be a Proc custom converter: (see [Custom Field
+# Converters](#class-CSV-label-Custom+Field+Converters)):
+#     str = ' foo  ,  bar  ,  baz  '
+#     # Without a converter
+#     array = CSV.parse_line(str)
+#     array # => [" foo  ", "  bar  ", "  baz  "]
+#     # With a custom converter
+#     array = CSV.parse_line(str, converters: proc {|field| field.strip })
+#     array # => ["foo", "bar", "baz"]
+#
+# See also [Custom Field Converters](#class-CSV-label-Custom+Field+Converters)
+#
+# ---
+#
+# Raises an exception if the converter is not a converter name or a Proc:
+#     str = 'foo,0'
+#     # Raises NoMethodError (undefined method `arity' for nil:NilClass)
+#     CSV.parse(str, converters: :foo)
+#
+# ###### Option `unconverted_fields`
+#
+# Specifies the boolean that determines whether unconverted field values are to
+# be available.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:unconverted_fields) # => nil
+#
+# The unconverted field values are those found in the source data, prior to any
+# conversions performed via option `converters`.
+#
+# When option `unconverted_fields` is `true`, each returned row (Array or
+# CSV::Row) has an added method, `unconverted_fields`, that returns the
+# unconverted field values:
+#     str = <<-EOT
+#     foo,0
+#     bar,1
+#     baz,2
+#     EOT
+#     # Without unconverted_fields
+#     csv = CSV.parse(str, converters: :integer)
+#     csv # => [["foo", 0], ["bar", 1], ["baz", 2]]
+#     csv.first.respond_to?(:unconverted_fields) # => false
+#     # With unconverted_fields
+#     csv = CSV.parse(str, converters: :integer, unconverted_fields: true)
+#     csv # => [["foo", 0], ["bar", 1], ["baz", 2]]
+#     csv.first.respond_to?(:unconverted_fields) # => true
+#     csv.first.unconverted_fields # => ["foo", "0"]
+#
+# ###### Option `headers`
+#
+# Specifies a boolean, Symbol, Array, or String to be used to define column
+# headers.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:headers) # => false
+#
+# ---
+#
+# Without `headers`:
+#     str = <<-EOT
+#     Name,Count
+#     foo,0
+#     bar,1
+#     bax,2
+#     EOT
+#     csv = CSV.new(str)
+#     csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
+#     csv.headers # => nil
+#     csv.shift # => ["Name", "Count"]
+#
+# ---
+#
+# If set to `true` or the Symbol `:first_row`, the first row of the data is
+# treated as a row of headers:
+#     str = <<-EOT
+#     Name,Count
+#     foo,0
+#     bar,1
+#     bax,2
+#     EOT
+#     csv = CSV.new(str, headers: true)
+#     csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:2 col_sep:"," row_sep:"\n" quote_char:"\"" headers:["Name", "Count"]>
+#     csv.headers # => ["Name", "Count"]
+#     csv.shift # => #<CSV::Row "Name":"bar" "Count":"1">
+#
+# ---
+#
+# If set to an Array, the Array elements are treated as headers:
+#     str = <<-EOT
+#     foo,0
+#     bar,1
+#     bax,2
+#     EOT
+#     csv = CSV.new(str, headers: ['Name', 'Count'])
+#     csv
+#     csv.headers # => ["Name", "Count"]
+#     csv.shift # => #<CSV::Row "Name":"bar" "Count":"1">
+#
+# ---
+#
+# If set to a String `str`, method `CSV::parse_line(str, options)` is called
+# with the current `options`, and the returned Array is treated as headers:
+#     str = <<-EOT
+#     foo,0
+#     bar,1
+#     bax,2
+#     EOT
+#     csv = CSV.new(str, headers: 'Name,Count')
+#     csv
+#     csv.headers # => ["Name", "Count"]
+#     csv.shift # => #<CSV::Row "Name":"bar" "Count":"1">
+#
+# ###### Option `return_headers`
+#
+# Specifies the boolean that determines whether method #shift returns or ignores
+# the header row.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:return_headers) # => false
+#
+# Examples:
+#     str = <<-EOT
+#     Name,Count
+#     foo,0
+#     bar,1
+#     bax,2
+#     EOT
+#     # Without return_headers first row is str.
+#     csv = CSV.new(str, headers: true)
+#     csv.shift # => #<CSV::Row "Name":"foo" "Count":"0">
+#     # With return_headers first row is headers.
+#     csv = CSV.new(str, headers: true, return_headers: true)
+#     csv.shift # => #<CSV::Row "Name":"Name" "Count":"Count">
+#
+# ###### Option `header_converters`
+#
+# Specifies converters to be used in parsing headers. See [Header
+# Converters](#class-CSV-label-Header+Converters)
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:header_converters) # => nil
+#
+# Identical in functionality to option
+# [converters](#class-CSV-label-Option+converters) except that:
+# *   The converters apply only to the header row.
+# *   The built-in header converters are `:downcase` and `:symbol`.
+#
+#
+# This section assumes prior execution of:
+#     str = <<-EOT
+#     Name,Value
+#     foo,0
+#     bar,1
+#     baz,2
+#     EOT
+#     # With no header converter
+#     table = CSV.parse(str, headers: true)
+#     table.headers # => ["Name", "Value"]
+#
+# The value may be a header converter name (see [Stored
+# Converters](#class-CSV-label-Stored+Converters)):
+#     table = CSV.parse(str, headers: true, header_converters: :downcase)
+#     table.headers # => ["name", "value"]
+#
+# The value may be a converter list (see [Converter
+# Lists](#class-CSV-label-Converter+Lists)):
+#     header_converters = [:downcase, :symbol]
+#     table = CSV.parse(str, headers: true, header_converters: header_converters)
+#     table.headers # => [:name, :value]
+#
+# The value may be a Proc custom converter (see [Custom Header
+# Converters](#class-CSV-label-Custom+Header+Converters)):
+#     upcase_converter = proc {|field| field.upcase }
+#     table = CSV.parse(str, headers: true, header_converters: upcase_converter)
+#     table.headers # => ["NAME", "VALUE"]
+#
+# See also [Custom Header Converters](#class-CSV-label-Custom+Header+Converters)
+#
+# ###### Option `skip_blanks`
+#
+# Specifies a boolean that determines whether blank lines in the input will be
+# ignored; a line that contains a column separator is not considered to be
+# blank.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:skip_blanks) # => false
+#
+# See also option [skiplines](#class-CSV-label-Option+skip_lines).
+#
+# For examples in this section:
+#     str = <<-EOT
+#     foo,0
+#
+#     bar,1
+#     baz,2
+#
+#     ,
+#     EOT
+#
+# Using the default, `false`:
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], [], ["bar", "1"], ["baz", "2"], [], [nil, nil]]
+#
+# Using `true`:
+#     ary = CSV.parse(str, skip_blanks: true)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"], [nil, nil]]
+#
+# Using a truthy value:
+#     ary = CSV.parse(str, skip_blanks: :foo)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"], [nil, nil]]
+#
+# ###### Option `skip_lines`
+#
+# Specifies an object to use in identifying comment lines in the input that are
+# to be ignored:
+# *   If a Regexp, ignores lines that match it.
+# *   If a String, converts it to a Regexp, ignores lines that match it.
+# *   If `nil`, no lines are considered to be comments.
+#
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:skip_lines) # => nil
+#
+# For examples in this section:
+#     str = <<-EOT
+#     # Comment
+#     foo,0
+#     bar,1
+#     baz,2
+#     # Another comment
+#     EOT
+#     str # => "# Comment\nfoo,0\nbar,1\nbaz,2\n# Another comment\n"
+#
+# Using the default, `nil`:
+#     ary = CSV.parse(str)
+#     ary # => [["# Comment"], ["foo", "0"], ["bar", "1"], ["baz", "2"], ["# Another comment"]]
+#
+# Using a Regexp:
+#     ary = CSV.parse(str, skip_lines: /^#/)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using a String:
+#     ary = CSV.parse(str, skip_lines: '#')
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# ---
+#
+# Raises an exception if given an object that is not a Regexp, a String, or
+# `nil`:
+#     # Raises ArgumentError (:skip_lines has to respond to #match: 0)
+#     CSV.parse(str, skip_lines: 0)
+#
+# ###### Option `strip`
+#
+# Specifies the boolean value that determines whether whitespace is stripped
+# from each input field.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:strip) # => false
+#
+# With default value `false`:
+#     ary = CSV.parse_line(' a , b ')
+#     ary # => [" a ", " b "]
+#
+# With value `true`:
+#     ary = CSV.parse_line(' a , b ', strip: true)
+#     ary # => ["a", "b"]
+#
+# ###### Option `liberal_parsing`
+#
+# Specifies the boolean value that determines whether CSV will attempt to parse
+# input not conformant with RFC 4180, such as double quotes in unquoted fields.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:liberal_parsing) # => false
+#
+# For examples in this section:
+#     str = 'is,this "three, or four",fields'
+#
+# Without `liberal_parsing`:
+#     # Raises CSV::MalformedCSVError (Illegal quoting in str 1.)
+#     CSV.parse_line(str)
+#
+# With `liberal_parsing`:
+#     ary = CSV.parse_line(str, liberal_parsing: true)
+#     ary # => ["is", "this \"three", " or four\"", "fields"]
+#
+# ###### Option `nil_value`
+#
+# Specifies the object that is to be substituted for each null (no-text) field.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:nil_value) # => nil
+#
+# With the default, `nil`:
+#     CSV.parse_line('a,,b,,c') # => ["a", nil, "b", nil, "c"]
+#
+# With a different object:
+#     CSV.parse_line('a,,b,,c', nil_value: 0) # => ["a", 0, "b", 0, "c"]
+#
+# ###### Option `empty_value`
+#
+# Specifies the object that is to be substituted for each field that has an
+# empty String.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:empty_value) # => "" (empty string)
+#
+# With the default, `""`:
+#     CSV.parse_line('a,"",b,"",c') # => ["a", "", "b", "", "c"]
 #
-# ### Shortcuts
+# With a different object:
+#     CSV.parse_line('a,"",b,"",c', empty_value: 'x') # => ["a", "x", "b", "x", "c"]
 #
-#     # Core extensions for converting one line
-#     csv_string = ["CSV", "data"].to_csv   # to CSV
-#     csv_array  = "CSV,String".parse_csv   # from CSV
+# #### Options for Generating
 #
-#     # CSV() method
-#     CSV             { |csv_out| csv_out << %w{my data here} }  # to $stdout
-#     CSV(csv = "")   { |csv_str| csv_str << %w{my data here} }  # to a String
-#     CSV($stderr)    { |csv_err| csv_err << %w{my data here} }  # to $stderr
-#     CSV($stdin)     { |csv_in|  csv_in.each { |row| p row } }  # from $stdin
+# Options for generating, described in detail below, include:
+# *   `row_sep`: Specifies the row separator; used to delimit rows.
+# *   `col_sep`: Specifies the column separator; used to delimit fields.
+# *   `quote_char`: Specifies the quote character; used to quote fields.
+# *   `write_headers`: Specifies whether headers are to be written.
+# *   `force_quotes`: Specifies whether each output field is to be quoted.
+# *   `quote_empty`: Specifies whether each empty output field is to be quoted.
+# *   `write_converters`: Specifies the field converters to be used in writing.
+# *   `write_nil_value`: Specifies the object that is to be substituted for each
+#     `nil`-valued field.
+# *   `write_empty_value`: Specifies the object that is to be substituted for
+#     each empty field.
 #
-# ## Data Conversion
 #
-# ### CSV with headers
+# ###### Option `row_sep`
+#
+# Specifies the row separator, a String or the Symbol `:auto` (see below), to be
+# used for both parsing and generating.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:row_sep) # => :auto
+#
+# ---
+#
+# When `row_sep` is a String, that String becomes the row separator. The String
+# will be transcoded into the data's Encoding before use.
+#
+# Using `"\n"`:
+#     row_sep = "\n"
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `|` (pipe):
+#     row_sep = '|'
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0|bar,1|baz,2|"
+#     ary = CSV.parse(str, row_sep: row_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `--` (two hyphens):
+#     row_sep = '--'
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0--bar,1--baz,2--"
+#     ary = CSV.parse(str, row_sep: row_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `''` (empty string):
+#     row_sep = ''
+#     str = CSV.generate(row_sep: row_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0bar,1baz,2"
+#     ary = CSV.parse(str, row_sep: row_sep)
+#     ary # => [["foo", "0bar", "1baz", "2"]]
+#
+# ---
+#
+# When `row_sep` is the Symbol `:auto` (the default), generating uses `"\n"` as
+# the row separator:
+#     str = CSV.generate do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#
+# Parsing, on the other hand, invokes auto-discovery of the row separator.
+#
+# Auto-discovery reads ahead in the data looking for the next `\r\n`, `\n`, or
+# `\r` sequence. The sequence will be selected even if it occurs in a quoted
+# field, assuming that you would have the same line endings there.
+#
+# Example:
+#     str = CSV.generate do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# The default `$INPUT_RECORD_SEPARATOR` (`$/`) is used if any of the following
+# is true:
+# *   None of those sequences is found.
+# *   Data is `ARGF`, `STDIN`, `STDOUT`, or `STDERR`.
+# *   The stream is only available for output.
+#
+#
+# Obviously, discovery takes a little time. Set manually if speed is important.
+# Also note that IO objects should be opened in binary mode on Windows if this
+# feature will be used as the line-ending translation can cause problems with
+# resetting the document position to where it was before the read ahead.
+#
+# ---
+#
+# Raises an exception if the given value is not String-convertible:
+#     row_sep = BasicObject.new
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.generate(ary, row_sep: row_sep)
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.parse(str, row_sep: row_sep)
+#
+# ###### Option `col_sep`
+#
+# Specifies the String field separator to be used for both parsing and
+# generating. The String will be transcoded into the data's Encoding before use.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:col_sep) # => "," (comma)
+#
+# Using the default (comma):
+#     str = CSV.generate do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo,0\nbar,1\nbaz,2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `:` (colon):
+#     col_sep = ':'
+#     str = CSV.generate(col_sep: col_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo:0\nbar:1\nbaz:2\n"
+#     ary = CSV.parse(str, col_sep: col_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `::` (two colons):
+#     col_sep = '::'
+#     str = CSV.generate(col_sep: col_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo::0\nbar::1\nbaz::2\n"
+#     ary = CSV.parse(str, col_sep: col_sep)
+#     ary # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Using `''` (empty string):
+#     col_sep = ''
+#     str = CSV.generate(col_sep: col_sep) do |csv|
+#       csv << [:foo, 0]
+#       csv << [:bar, 1]
+#       csv << [:baz, 2]
+#     end
+#     str # => "foo0\nbar1\nbaz2\n"
+#
+# ---
+#
+# Raises an exception if parsing with the empty String:
+#     col_sep = ''
+#     # Raises ArgumentError (:col_sep must be 1 or more characters: "")
+#     CSV.parse("foo0\nbar1\nbaz2\n", col_sep: col_sep)
+#
+# Raises an exception if the given value is not String-convertible:
+#     col_sep = BasicObject.new
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.generate(line, col_sep: col_sep)
+#     # Raises NoMethodError (undefined method `to_s' for #<BasicObject:>)
+#     CSV.parse(str, col_sep: col_sep)
+#
+# ###### Option `quote_char`
+#
+# Specifies the character (String of length 1) used used to quote fields in both
+# parsing and generating. This String will be transcoded into the data's
+# Encoding before use.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:quote_char) # => "\"" (double quote)
+#
+# This is useful for an application that incorrectly uses `'` (single-quote) to
+# quote fields, instead of the correct `"` (double-quote).
+#
+# Using the default (double quote):
+#     str = CSV.generate do |csv|
+#       csv << ['foo', 0]
+#       csv << ["'bar'", 1]
+#       csv << ['"baz"', 2]
+#     end
+#     str # => "foo,0\n'bar',1\n\"\"\"baz\"\"\",2\n"
+#     ary = CSV.parse(str)
+#     ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]
+#
+# Using `'` (single-quote):
+#     quote_char = "'"
+#     str = CSV.generate(quote_char: quote_char) do |csv|
+#       csv << ['foo', 0]
+#       csv << ["'bar'", 1]
+#       csv << ['"baz"', 2]
+#     end
+#     str # => "foo,0\n'''bar''',1\n\"baz\",2\n"
+#     ary = CSV.parse(str, quote_char: quote_char)
+#     ary # => [["foo", "0"], ["'bar'", "1"], ["\"baz\"", "2"]]
+#
+# ---
+#
+# Raises an exception if the String length is greater than 1:
+#     # Raises ArgumentError (:quote_char has to be nil or a single character String)
+#     CSV.new('', quote_char: 'xx')
+#
+# Raises an exception if the value is not a String:
+#     # Raises ArgumentError (:quote_char has to be nil or a single character String)
+#     CSV.new('', quote_char: :foo)
+#
+# ###### Option `write_headers`
+#
+# Specifies the boolean that determines whether a header row is included in the
+# output; ignored if there are no headers.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:write_headers) # => nil
+#
+# Without `write_headers`:
+#     file_path = 't.csv'
+#     CSV.open(file_path,'w',
+#         :headers => ['Name','Value']
+#       ) do |csv|
+#         csv << ['foo', '0']
+#     end
+#     CSV.open(file_path) do |csv|
+#       csv.shift
+#     end # => ["foo", "0"]
+#
+# With `write_headers`":
+#     CSV.open(file_path,'w',
+#         :write_headers=> true,
+#         :headers => ['Name','Value']
+#       ) do |csv|
+#         csv << ['foo', '0']
+#     end
+#     CSV.open(file_path) do |csv|
+#       csv.shift
+#     end # => ["Name", "Value"]
+#
+# ###### Option `force_quotes`
+#
+# Specifies the boolean that determines whether each output field is to be
+# double-quoted.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:force_quotes) # => false
+#
+# For examples in this section:
+#     ary = ['foo', 0, nil]
+#
+# Using the default, `false`:
+#     str = CSV.generate_line(ary)
+#     str # => "foo,0,\n"
+#
+# Using `true`:
+#     str = CSV.generate_line(ary, force_quotes: true)
+#     str # => "\"foo\",\"0\",\"\"\n"
+#
+# ###### Option `quote_empty`
+#
+# Specifies the boolean that determines whether an empty value is to be
+# double-quoted.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:quote_empty) # => true
+#
+# With the default `true`:
+#     CSV.generate_line(['"', ""]) # => "\"\"\"\",\"\"\n"
+#
+# With `false`:
+#     CSV.generate_line(['"', ""], quote_empty: false) # => "\"\"\"\",\n"
+#
+# ###### Option `write_converters`
+#
+# Specifies converters to be used in generating fields. See [Write
+# Converters](#class-CSV-label-Write+Converters)
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:write_converters) # => nil
+#
+# With no write converter:
+#     str = CSV.generate_line(["\na\n", "\tb\t", " c "])
+#     str # => "\"\na\n\",\tb\t, c \n"
+#
+# With a write converter:
+#     strip_converter = proc {|field| field.strip }
+#     str = CSV.generate_line(["\na\n", "\tb\t", " c "], write_converters: strip_converter)
+#     str # => "a,b,c\n"
+#
+# With two write converters (called in order):
+#     upcase_converter = proc {|field| field.upcase }
+#     downcase_converter = proc {|field| field.downcase }
+#     write_converters = [upcase_converter, downcase_converter]
+#     str = CSV.generate_line(['a', 'b', 'c'], write_converters: write_converters)
+#     str # => "a,b,c\n"
+#
+# See also [Write Converters](#class-CSV-label-Write+Converters)
+#
+# ---
+#
+# Raises an exception if the converter returns a value that is neither `nil` nor
+# String-convertible:
+#     bad_converter = proc {|field| BasicObject.new }
+#     # Raises NoMethodError (undefined method `is_a?' for #<BasicObject:>)
+#     CSV.generate_line(['a', 'b', 'c'], write_converters: bad_converter)#
+#
+# ###### Option `write_nil_value`
+#
+# Specifies the object that is to be substituted for each `nil`-valued field.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:write_nil_value) # => nil
+#
+# Without the option:
+#     str = CSV.generate_line(['a', nil, 'c', nil])
+#     str # => "a,,c,\n"
+#
+# With the option:
+#     str = CSV.generate_line(['a', nil, 'c', nil], write_nil_value: "x")
+#     str # => "a,x,c,x\n"
+#
+# ###### Option `write_empty_value`
+#
+# Specifies the object that is to be substituted for each field that has an
+# empty String.
+#
+# Default value:
+#     CSV::DEFAULT_OPTIONS.fetch(:write_empty_value) # => ""
+#
+# Without the option:
+#     str = CSV.generate_line(['a', '', 'c', ''])
+#     str # => "a,\"\",c,\"\"\n"
+#
+# With the option:
+#     str = CSV.generate_line(['a', '', 'c', ''], write_empty_value: "x")
+#     str # => "a,x,c,x\n"
+#
+# ### CSV with Headers
 #
 # CSV allows to specify column names of CSV file, whether they are in data, or
 # provided separately. If headers are specified, reading methods return an
 # instance of CSV::Table, consisting of CSV::Row.
 #
-#     # Headers are part of data
-#     data = CSV.parse(<<~ROWS, headers: true)
-#       Name,Department,Salary
-#       Bob,Engineering,1000
-#       Jane,Sales,2000
-#       John,Management,5000
-#     ROWS
+#     # Headers are part of data
+#     data = CSV.parse(<<~ROWS, headers: true)
+#       Name,Department,Salary
+#       Bob,Engineering,1000
+#       Jane,Sales,2000
+#       John,Management,5000
+#     ROWS
+#
+#     data.class      #=> CSV::Table
+#     data.first      #=> #<CSV::Row "Name":"Bob" "Department":"Engineering" "Salary":"1000">
+#     data.first.to_h #=> {"Name"=>"Bob", "Department"=>"Engineering", "Salary"=>"1000"}
+#
+#     # Headers provided by developer
+#     data = CSV.parse('Bob,Engineering,1000', headers: %i[name department salary])
+#     data.first      #=> #<CSV::Row name:"Bob" department:"Engineering" salary:"1000">
+#
+# ### Converters
+#
+# By default, each value (field or header) parsed by CSV is formed into a
+# String. You can use a *field* *converter* or  *header* *converter* to
+# intercept and modify the parsed values:
+# *   See [Field Converters](#class-CSV-label-Field+Converters).
+# *   See [Header Converters](#class-CSV-label-Header+Converters).
+#
+#
+# Also by default, each value to be written during generation is written
+# 'as-is'. You can use a *write* *converter* to modify values before writing.
+# *   See [Write Converters](#class-CSV-label-Write+Converters).
+#
+#
+# #### Specifying Converters
+#
+# You can specify converters for parsing or generating in the `options` argument
+# to various CSV methods:
+# *   Option `converters` for converting parsed field values.
+# *   Option `header_converters` for converting parsed header values.
+# *   Option `write_converters` for converting values to be written (generated).
+#
+#
+# There are three forms for specifying converters:
+# *   A converter proc: executable code to be used for conversion.
+# *   A converter name: the name of a stored converter.
+# *   A converter list: an array of converter procs, converter names, and
+#     converter lists.
+#
+#
+# ##### Converter Procs
+#
+# This converter proc, `strip_converter`, accepts a value `field` and returns
+# `field.strip`:
+#     strip_converter = proc {|field| field.strip }
+#
+# In this call to `CSV.parse`, the keyword argument `converters:
+# string_converter` specifies that:
+# *   Proc `string_converter` is to be called for each parsed field.
+# *   The converter's return value is to replace the `field` value.
+#
+# Example:
+#     string = " foo , 0 \n bar , 1 \n baz , 2 \n"
+#     array = CSV.parse(string, converters: strip_converter)
+#     array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# A converter proc can receive a second argument, `field_info`, that contains
+# details about the field. This modified `strip_converter` displays its
+# arguments:
+#     strip_converter = proc do |field, field_info|
+#       p [field, field_info]
+#       field.strip
+#     end
+#     string = " foo , 0 \n bar , 1 \n baz , 2 \n"
+#     array = CSV.parse(string, converters: strip_converter)
+#     array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# Output:
+#     [" foo ", #<struct CSV::FieldInfo index=0, line=1, header=nil>]
+#     [" 0 ", #<struct CSV::FieldInfo index=1, line=1, header=nil>]
+#     [" bar ", #<struct CSV::FieldInfo index=0, line=2, header=nil>]
+#     [" 1 ", #<struct CSV::FieldInfo index=1, line=2, header=nil>]
+#     [" baz ", #<struct CSV::FieldInfo index=0, line=3, header=nil>]
+#     [" 2 ", #<struct CSV::FieldInfo index=1, line=3, header=nil>]
+#
+# Each CSV::FieldInfo object shows:
+# *   The 0-based field index.
+# *   The 1-based line index.
+# *   The field header, if any.
+#
+#
+# ##### Stored Converters
+#
+# A converter may be given a name and stored in a structure where the parsing
+# methods can find it by name.
+#
+# The storage structure for field converters is the Hash CSV::Converters. It has
+# several built-in converter procs:
+# *   `:integer`: converts each String-embedded integer into a true Integer.
+# *   `:float`: converts each String-embedded float into a true Float.
+# *   `:date`: converts each String-embedded date into a true Date.
+# *   `:date_time`: converts each String-embedded date-time into a true DateTime
+#
+# . This example creates a converter proc, then stores it:
+#     strip_converter = proc {|field| field.strip }
+#     CSV::Converters[:strip] = strip_converter
+#
+# Then the parsing method call can refer to the converter by its name, `:strip`:
+#     string = " foo , 0 \n bar , 1 \n baz , 2 \n"
+#     array = CSV.parse(string, converters: :strip)
+#     array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# The storage structure for header converters is the Hash CSV::HeaderConverters,
+# which works in the same way. It also has built-in converter procs:
+# *   `:downcase`: Downcases each header.
+# *   `:symbol`: Converts each header to a Symbol.
+#
+#
+# There is no such storage structure for write headers.
+#
+# In order for the parsing methods to access stored converters in
+# non-main-Ractors, the storage structure must be made shareable first.
+# Therefore, `Ractor.make_shareable(CSV::Converters)` and
+# `Ractor.make_shareable(CSV::HeaderConverters)` must be called before the
+# creation of Ractors that use the converters stored in these structures. (Since
+# making the storage structures shareable involves freezing them, any custom
+# converters that are to be used must be added first.)
+#
+# ##### Converter Lists
+#
+# A *converter* *list* is an Array that may include any assortment of:
+# *   Converter procs.
+# *   Names of stored converters.
+# *   Nested converter lists.
+#
+#
+# Examples:
+#     numeric_converters = [:integer, :float]
+#     date_converters = [:date, :date_time]
+#     [numeric_converters, strip_converter]
+#     [strip_converter, date_converters, :float]
+#
+# Like a converter proc, a converter list may be named and stored in either
+# CSV::Converters or CSV::HeaderConverters:
+#     CSV::Converters[:custom] = [strip_converter, date_converters, :float]
+#     CSV::HeaderConverters[:custom] = [:downcase, :symbol]
+#
+# There are two built-in converter lists:
+#     CSV::Converters[:numeric] # => [:integer, :float]
+#     CSV::Converters[:all] # => [:date_time, :numeric]
+#
+# #### Field Converters
+#
+# With no conversion, all parsed fields in all rows become Strings:
+#     string = "foo,0\nbar,1\nbaz,2\n"
+#     ary = CSV.parse(string)
+#     ary # => # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# When you specify a field converter, each parsed field is passed to the
+# converter; its return value becomes the stored value for the field. A
+# converter might, for example, convert an integer embedded in a String into a
+# true Integer. (In fact, that's what built-in field converter `:integer` does.)
+#
+# There are three ways to use field converters.
+#
+# *   Using option [converters](#class-CSV-label-Option+converters) with a
+#     parsing method:
+#         ary = CSV.parse(string, converters: :integer)
+#         ary # => [0, 1, 2] # => [["foo", 0], ["bar", 1], ["baz", 2]]
+#
+# *   Using option [converters](#class-CSV-label-Option+converters) with a new
+#     CSV instance:
+#         csv = CSV.new(string, converters: :integer)
+#         # Field converters in effect:
+#         csv.converters # => [:integer]
+#         csv.read # => [["foo", 0], ["bar", 1], ["baz", 2]]
+#
+# *   Using method #convert to add a field converter to a CSV instance:
+#         csv = CSV.new(string)
+#         # Add a converter.
+#         csv.convert(:integer)
+#         csv.converters # => [:integer]
+#         csv.read # => [["foo", 0], ["bar", 1], ["baz", 2]]
+#
+#
+# Installing a field converter does not affect already-read rows:
+#     csv = CSV.new(string)
+#     csv.shift # => ["foo", "0"]
+#     # Add a converter.
+#     csv.convert(:integer)
+#     csv.converters # => [:integer]
+#     csv.read # => [["bar", 1], ["baz", 2]]
+#
+# There are additional built-in converters, and custom converters are also
+# supported.
+#
+# ##### Built-In Field Converters
+#
+# The built-in field converters are in Hash CSV::Converters:
+# *   Each key is a field converter name.
+# *   Each value is one of:
+#     *   A Proc field converter.
+#     *   An Array of field converter names.
+#
+#
+#
+# Display:
+#     CSV::Converters.each_pair do |name, value|
+#       if value.kind_of?(Proc)
+#         p [name, value.class]
+#       else
+#         p [name, value]
+#       end
+#     end
+#
+# Output:
+#     [:integer, Proc]
+#     [:float, Proc]
+#     [:numeric, [:integer, :float]]
+#     [:date, Proc]
+#     [:date_time, Proc]
+#     [:all, [:date_time, :numeric]]
+#
+# Each of these converters transcodes values to UTF-8 before attempting
+# conversion. If a value cannot be transcoded to UTF-8 the conversion will fail
+# and the value will remain unconverted.
+#
+# Converter `:integer` converts each field that Integer() accepts:
+#     data = '0,1,2,x'
+#     # Without the converter
+#     csv = CSV.parse_line(data)
+#     csv # => ["0", "1", "2", "x"]
+#     # With the converter
+#     csv = CSV.parse_line(data, converters: :integer)
+#     csv # => [0, 1, 2, "x"]
+#
+# Converter `:float` converts each field that Float() accepts:
+#     data = '1.0,3.14159,x'
+#     # Without the converter
+#     csv = CSV.parse_line(data)
+#     csv # => ["1.0", "3.14159", "x"]
+#     # With the converter
+#     csv = CSV.parse_line(data, converters: :float)
+#     csv # => [1.0, 3.14159, "x"]
+#
+# Converter `:numeric` converts with both `:integer` and `:float`..
+#
+# Converter `:date` converts each field that Date::parse accepts:
+#     data = '2001-02-03,x'
+#     # Without the converter
+#     csv = CSV.parse_line(data)
+#     csv # => ["2001-02-03", "x"]
+#     # With the converter
+#     csv = CSV.parse_line(data, converters: :date)
+#     csv # => [#<Date: 2001-02-03 ((2451944j,0s,0n),+0s,2299161j)>, "x"]
+#
+# Converter `:date_time` converts each field that DateTime::parse accepts:
+#     data = '2020-05-07T14:59:00-05:00,x'
+#     # Without the converter
+#     csv = CSV.parse_line(data)
+#     csv # => ["2020-05-07T14:59:00-05:00", "x"]
+#     # With the converter
+#     csv = CSV.parse_line(data, converters: :date_time)
+#     csv # => [#<DateTime: 2020-05-07T14:59:00-05:00 ((2458977j,71940s,0n),-18000s,2299161j)>, "x"]
+#
+# Converter `:numeric` converts with both `:date_time` and `:numeric`..
+#
+# As seen above, method #convert adds converters to a CSV instance, and method
+# #converters returns an Array of the converters in effect:
+#     csv = CSV.new('0,1,2')
+#     csv.converters # => []
+#     csv.convert(:integer)
+#     csv.converters # => [:integer]
+#     csv.convert(:date)
+#     csv.converters # => [:integer, :date]
+#
+# ##### Custom Field Converters
+#
+# You can define a custom field converter:
+#     strip_converter = proc {|field| field.strip }
+#     string = " foo , 0 \n bar , 1 \n baz , 2 \n"
+#     array = CSV.parse(string, converters: strip_converter)
+#     array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# You can register the converter in Converters Hash, which allows you to refer
+# to it by name:
+#     CSV::Converters[:strip] = strip_converter
+#     string = " foo , 0 \n bar , 1 \n baz , 2 \n"
+#     array = CSV.parse(string, converters: :strip)
+#     array # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+#
+# #### Header Converters
+#
+# Header converters operate only on headers (and not on other rows).
+#
+# There are three ways to use header converters; these examples use built-in
+# header converter `:dowhcase`, which downcases each parsed header.
+#
+# *   Option `header_converters` with a singleton parsing method:
+#         string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"
+#         tbl = CSV.parse(string, headers: true, header_converters: :downcase)
+#         tbl.class # => CSV::Table
+#         tbl.headers # => ["name", "count"]
+#
+# *   Option `header_converters` with a new CSV instance:
+#         csv = CSV.new(string, header_converters: :downcase)
+#         # Header converters in effect:
+#         csv.header_converters # => [:downcase]
+#         tbl = CSV.parse(string, headers: true)
+#         tbl.headers # => ["Name", "Count"]
+#
+# *   Method #header_convert adds a header converter to a CSV instance:
+#         csv = CSV.new(string)
+#         # Add a header converter.
+#         csv.header_convert(:downcase)
+#         csv.header_converters # => [:downcase]
+#         tbl = CSV.parse(string, headers: true)
+#         tbl.headers # => ["Name", "Count"]
+#
+#
+# ##### Built-In Header Converters
+#
+# The built-in header converters are in Hash CSV::HeaderConverters. The keys
+# there are the names of the converters:
+#     CSV::HeaderConverters.keys # => [:downcase, :symbol]
+#
+# Converter `:downcase` converts each header by downcasing it:
+#     string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"
+#     tbl = CSV.parse(string, headers: true, header_converters: :downcase)
+#     tbl.class # => CSV::Table
+#     tbl.headers # => ["name", "count"]
+#
+# Converter `:symbol` converts each header by making it into a Symbol:
+#     string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"
+#     tbl = CSV.parse(string, headers: true, header_converters: :symbol)
+#     tbl.headers # => [:name, :count]
+#
+# Details:
+# *   Strips leading and trailing whitespace.
+# *   Downcases the header.
+# *   Replaces embedded spaces with underscores.
+# *   Removes non-word characters.
+# *   Makes the string into a Symbol.
+#
 #
-#     data.class      #=> CSV::Table
-#     data.first      #=> #<CSV::Row "Name":"Bob" "Department":"Engineering" "Salary":"1000">
-#     data.first.to_h #=> {"Name"=>"Bob", "Department"=>"Engineering", "Salary"=>"1000"}
+# ##### Custom Header Converters
 #
-#     # Headers provided by developer
-#     data = CSV.parse('Bob,Engineering,1000', headers: %i[name department salary])
-#     data.first      #=> #<CSV::Row name:"Bob" department:"Engineering" salary:"1000">
+# You can define a custom header converter:
+#     upcase_converter = proc {|header| header.upcase }
+#     string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+#     table = CSV.parse(string, headers: true, header_converters: upcase_converter)
+#     table # => #<CSV::Table mode:col_or_row row_count:4>
+#     table.headers # => ["NAME", "VALUE"]
 #
-# ### Typed data reading
+# You can register the converter in HeaderConverters Hash, which allows you to
+# refer to it by name:
+#     CSV::HeaderConverters[:upcase] = upcase_converter
+#     table = CSV.parse(string, headers: true, header_converters: :upcase)
+#     table # => #<CSV::Table mode:col_or_row row_count:4>
+#     table.headers # => ["NAME", "VALUE"]
 #
-# CSV allows to provide a set of data *converters* e.g. transformations to try
-# on input data. Converter could be a symbol from CSV::Converters constant's
-# keys, or lambda.
+# ##### Write Converters
 #
-#     # Without any converters:
-#     CSV.parse('Bob,2018-03-01,100')
-#     #=> [["Bob", "2018-03-01", "100"]]
+# When you specify a write converter for generating CSV, each field to be
+# written is passed to the converter; its return value becomes the new value for
+# the field. A converter might, for example, strip whitespace from a field.
 #
-#     # With built-in converters:
-#     CSV.parse('Bob,2018-03-01,100', converters: %i[numeric date])
-#     #=> [["Bob", #<Date: 2018-03-01>, 100]]
+# Using no write converter (all fields unmodified):
+#     output_string = CSV.generate do |csv|
+#       csv << [' foo ', 0]
+#       csv << [' bar ', 1]
+#       csv << [' baz ', 2]
+#     end
+#     output_string # => " foo ,0\n bar ,1\n baz ,2\n"
 #
-#     # With custom converters:
-#     CSV.parse('Bob,2018-03-01,100', converters: [->(v) { Time.parse(v) rescue v }])
-#     #=> [["Bob", 2018-03-01 00:00:00 +0200, "100"]]
+# Using option `write_converters` with two custom write converters:
+#     strip_converter = proc {|field| field.respond_to?(:strip) ? field.strip : field }
+#     upcase_converter = proc {|field| field.respond_to?(:upcase) ? field.upcase : field }
+#     write_converters = [strip_converter, upcase_converter]
+#     output_string = CSV.generate(write_converters: write_converters) do |csv|
+#       csv << [' foo ', 0]
+#       csv << [' bar ', 1]
+#       csv << [' baz ', 2]
+#     end
+#     output_string # => "FOO,0\nBAR,1\nBAZ,2\n"
 #
-# ## CSV and Character Encodings (M17n or Multilingualization)
+# ### Character Encodings (M17n or Multilingualization)
 #
 # This new CSV parser is m17n savvy.  The parser works in the Encoding of the IO
 # or String object being read from or written to. Your data is never transcoded
@@ -162,287 +1651,605 @@ class CSV < Object
   include Enumerable[untyped]
   extend Forwardable
 
-  # This method is intended as the primary interface for reading CSV files. You
-  # pass a `path` and any `options` you wish to set for the read. Each row of file
-  # will be passed to the provided `block` in turn.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - foreach(path, mode='r', **options) {|row| ... )
+  #   - foreach(io, mode='r', **options {|row| ... )
+  #   - foreach(path, mode='r', headers: ..., **options) {|row| ... )
+  #   - foreach(io, mode='r', headers: ..., **options {|row| ... )
+  #   - foreach(path, mode='r', **options) -> new_enumerator
+  #   - foreach(io, mode='r', **options -> new_enumerator
+  # -->
+  # Calls the block with each row read from source `path` or `io`.
+  #
+  # *   Argument `path`, if given, must be the path to a file.
+  # *   Argument `io` should be an IO object that is:
+  #     *   Open for reading; on return, the IO object will be closed.
+  #     *   Positioned at the beginning. To position at the end, for appending,
+  #         use method CSV.generate. For any other positioning, pass a preset
+  #         StringIO object instead.
+  #
+  # *   Argument `mode`, if given, must be a File mode See [Open
+  #     Mode](IO.html#method-c-new-label-Open+Mode).
+  # *   Arguments `**options` must be keyword options. See [Options for
+  #     Parsing](#class-CSV-label-Options+for+Parsing).
+  # *   This method optionally accepts an additional `:encoding` option that you
+  #     can use to specify the Encoding of the data read from `path` or `io`. You
+  #     must provide this unless your data is in the encoding given by
+  #     `Encoding::default_external`. Parsing will use this to determine how to
+  #     parse the data. You may provide a second Encoding to have the data
+  #     transcoded as it is read. For example,
+  #         encoding: 'UTF-32BE:UTF-8'
+  #
+  #     would read `UTF-32BE` data from the file but transcode it to `UTF-8`
+  #     before parsing.
+  #
+  #
+  # ###### Without Option `headers`
+  #
+  # Without option `headers`, returns each row as an Array object.
+  #
+  # These examples assume prior execution of:
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #
+  # Read rows from a file at `path`:
+  #     CSV.foreach(path) {|row| p row }
+  #
+  # Output:
+  #     ["foo", "0"]
+  #     ["bar", "1"]
+  #     ["baz", "2"]
+  #
+  # Read rows from an IO object:
+  #     File.open(path) do |file|
+  #       CSV.foreach(file) {|row| p row }
+  #     end
+  #
+  # Output:
+  #     ["foo", "0"]
+  #     ["bar", "1"]
+  #     ["baz", "2"]
+  #
+  # Returns a new Enumerator if no block given:
+  #     CSV.foreach(path) # => #<Enumerator: CSV:foreach("t.csv", "r")>
+  #     CSV.foreach(File.open(path)) # => #<Enumerator: CSV:foreach(#<File:t.csv>, "r")>
+  #
+  # Issues a warning if an encoding is unsupported:
+  #     CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| }
+  #
+  # Output:
+  #     warning: Unsupported encoding foo ignored
+  #     warning: Unsupported encoding bar ignored
+  #
+  # ###### With Option `headers`
+  #
+  # With {option `headers`[}](#class-CSV-label-Option+headers), returns each row
+  # as a CSV::Row object.
+  #
+  # These examples assume prior execution of:
+  #     string = "Name,Count\nfoo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #
+  # Read rows from a file at `path`:
+  #     CSV.foreach(path, headers: true) {|row| p row }
+  #
+  # Output:
+  #     #<CSV::Row "Name":"foo" "Count":"0">
+  #     #<CSV::Row "Name":"bar" "Count":"1">
+  #     #<CSV::Row "Name":"baz" "Count":"2">
+  #
+  # Read rows from an IO object:
+  #     File.open(path) do |file|
+  #       CSV.foreach(file, headers: true) {|row| p row }
+  #     end
+  #
+  # Output:
+  #     #<CSV::Row "Name":"foo" "Count":"0">
+  #     #<CSV::Row "Name":"bar" "Count":"1">
+  #     #<CSV::Row "Name":"baz" "Count":"2">
+  #
+  # ---
+  #
+  # Raises an exception if `path` is a String, but not the path to a readable
+  # file:
+  #     # Raises Errno::ENOENT (No such file or directory @ rb_sysopen - nosuch.csv):
+  #     CSV.foreach('nosuch.csv') {|row| }
   #
-  # The `options` parameter can be anything CSV::new() understands. This method
-  # also understands an additional `:encoding` parameter that you can use to
-  # specify the Encoding of the data in the file to be read. You must provide this
-  # unless your data is in Encoding::default_external(). CSV will use this to
-  # determine how to parse the data. You may provide a second Encoding to have the
-  # data transcoded as it is read. For example, `encoding: "UTF-32BE:UTF-8"` would
-  # read UTF-32BE data from the file but transcode it to UTF-8 before CSV parses
-  # it.
+  # Raises an exception if `io` is an IO object, but not open for reading:
+  #     io = File.open(path, 'w') {|row| }
+  #     # Raises TypeError (no implicit conversion of nil into String):
+  #     CSV.foreach(io) {|row| }
+  #
+  # Raises an exception if `mode` is invalid:
+  #     # Raises ArgumentError (invalid access mode nosuch):
+  #     CSV.foreach(path, 'nosuch') {|row| }
   #
   def self.foreach: [U] (String | IO | StringIO path, ?::Hash[Symbol, U] options) { (::Array[String?] arg0) -> void } -> void
 
-  # This constructor will wrap either a String or IO object passed in `data` for
-  # reading and/or writing. In addition to the CSV instance methods, several IO
-  # methods are delegated. (See CSV::open() for a complete list.) If you pass a
-  # String for `data`, you can later retrieve it (after writing to it, for
-  # example) with CSV.string().
-  #
-  # Note that a wrapped String will be positioned at the beginning (for reading).
-  # If you want it at the end (for writing), use CSV::generate(). If you want any
-  # other positioning, pass a preset StringIO object instead.
-  #
-  # You may set any reading and/or writing preferences in the `options` Hash.
-  # Available options are:
-  #
-  # **`:col_sep`**
-  # :   The String placed between each field. This String will be transcoded into
-  #     the data's Encoding before parsing.
-  # **`:row_sep`**
-  # :   The String appended to the end of each row. This can be set to the special
-  #     `:auto` setting, which requests that CSV automatically discover this from
-  #     the data. Auto-discovery reads ahead in the data looking for the next
-  #     `"\r\n"`, `"\n"`, or `"\r"` sequence. A sequence will be selected even if
-  #     it occurs in a quoted field, assuming that you would have the same line
-  #     endings there. If none of those sequences is found, `data` is `ARGF`,
-  #     `STDIN`, `STDOUT`, or `STDERR`, or the stream is only available for
-  #     output, the default `$INPUT_RECORD_SEPARATOR` (`$/`) is used. Obviously,
-  #     discovery takes a little time. Set manually if speed is important. Also
-  #     note that IO objects should be opened in binary mode on Windows if this
-  #     feature will be used as the line-ending translation can cause problems
-  #     with resetting the document position to where it was before the read
-  #     ahead. This String will be transcoded into the data's Encoding before
-  #     parsing.
-  # **`:quote_char`**
-  # :   The character used to quote fields. This has to be a single character
-  #     String. This is useful for application that incorrectly use `'` as the
-  #     quote character instead of the correct `"`. CSV will always consider a
-  #     double sequence of this character to be an escaped quote. This String will
-  #     be transcoded into the data's Encoding before parsing.
-  # **`:field_size_limit`**
-  # :   This is a maximum size CSV will read ahead looking for the closing quote
-  #     for a field. (In truth, it reads to the first line ending beyond this
-  #     size.) If a quote cannot be found within the limit CSV will raise a
-  #     MalformedCSVError, assuming the data is faulty. You can use this limit to
-  #     prevent what are effectively DoS attacks on the parser. However, this
-  #     limit can cause a legitimate parse to fail and thus is set to `nil`, or
-  #     off, by default.
-  # **`:converters`**
-  # :   An Array of names from the Converters Hash and/or lambdas that handle
-  #     custom conversion. A single converter doesn't have to be in an Array. All
-  #     built-in converters try to transcode fields to UTF-8 before converting.
-  #     The conversion will fail if the data cannot be transcoded, leaving the
-  #     field unchanged.
-  # **`:unconverted_fields`**
-  # :   If set to `true`, an unconverted_fields() method will be added to all
-  #     returned rows (Array or CSV::Row) that will return the fields as they were
-  #     before conversion. Note that `:headers` supplied by Array or String were
-  #     not fields of the document and thus will have an empty Array attached.
-  # **`:headers`**
-  # :   If set to `:first_row` or `true`, the initial row of the CSV file will be
-  #     treated as a row of headers. If set to an Array, the contents will be used
-  #     as the headers. If set to a String, the String is run through a call of
-  #     CSV::parse_line() with the same `:col_sep`, `:row_sep`, and `:quote_char`
-  #     as this instance to produce an Array of headers. This setting causes
-  #     CSV#shift() to return rows as CSV::Row objects instead of Arrays and
-  #     CSV#read() to return CSV::Table objects instead of an Array of Arrays.
-  # **`:return_headers`**
-  # :   When `false`, header rows are silently swallowed. If set to `true`, header
-  #     rows are returned in a CSV::Row object with identical headers and fields
-  #     (save that the fields do not go through the converters).
-  # **`:write_headers`**
-  # :   When `true` and `:headers` is set, a header row will be added to the
-  #     output.
-  # **`:header_converters`**
-  # :   Identical in functionality to `:converters` save that the conversions are
-  #     only made to header rows. All built-in converters try to transcode headers
-  #     to UTF-8 before converting. The conversion will fail if the data cannot be
-  #     transcoded, leaving the header unchanged.
-  # **`:skip_blanks`**
-  # :   When setting a `true` value, CSV will skip over any empty rows. Note that
-  #     this setting will not skip rows that contain column separators, even if
-  #     the rows contain no actual data. If you want to skip rows that contain
-  #     separators but no content, consider using `:skip_lines`, or inspecting
-  #     fields.compact.empty? on each row.
-  # **`:force_quotes`**
-  # :   When setting a `true` value, CSV will quote all CSV fields it creates.
-  # **`:skip_lines`**
-  # :   When setting an object responding to `match`, every line matching it is
-  #     considered a comment and ignored during parsing. When set to a String, it
-  #     is first converted to a Regexp. When set to `nil` no line is considered a
-  #     comment. If the passed object does not respond to `match`, `ArgumentError`
-  #     is thrown.
-  # **`:liberal_parsing`**
-  # :   When setting a `true` value, CSV will attempt to parse input not
-  #     conformant with RFC 4180, such as double quotes in unquoted fields.
-  # **`:nil_value`**
-  # :   When set an object, any values of an empty field is replaced by the set
-  #     object, not nil.
-  # **`:empty_value`**
-  # :   When setting an object, any values of a blank string field is replaced by
-  #     the set object.
-  # **`:quote_empty`**
-  # :   When setting a `true` value, CSV will quote empty values with double
-  #     quotes. When `false`, CSV will emit an empty string for an empty field
-  #     value.
-  # **`:write_converters`**
-  # :   Converts values on each line with the specified `Proc` object(s), which
-  #     receive a `String` value and return a `String` or `nil` value. When an
-  #     array is specified, each converter will be applied in order.
-  # **`:write_nil_value`**
-  # :   When a `String` value, `nil` value(s) on each line will be replaced with
-  #     the specified value.
-  # **`:write_empty_value`**
-  # :   When a `String` or `nil` value, empty value(s) on each line will be
-  #     replaced with the specified value.
-  # **`:strip`**
-  # :   When setting a `true` value, CSV will strip "t\r\n\f\v" around the values.
-  #     If you specify a string instead of `true`, CSV will strip string. The
-  #     length of the string must be 1.
-  #
-  #
-  # See CSV::DEFAULT_OPTIONS for the default settings.
-  #
-  # Options cannot be overridden in the instance methods for performance reasons,
-  # so be sure to set what you want here.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - CSV.new(string)
+  #   - CSV.new(io)
+  #   - CSV.new(string, **options)
+  #   - CSV.new(io, **options)
+  # -->
+  # Returns the new CSV object created using `string` or `io` and the specified
+  # `options`.
+  #
+  # *   Argument `string` should be a String object; it will be put into a new
+  #     StringIO object positioned at the beginning.
+  # *   Argument `io` should be an IO object that is:
+  #     *   Open for reading; on return, the IO object will be closed.
+  #     *   Positioned at the beginning. To position at the end, for appending,
+  #         use method CSV.generate. For any other positioning, pass a preset
+  #         StringIO object instead.
+  #
+  # *   Argument `options`: See:
+  #     *   [Options for Parsing](#class-CSV-label-Options+for+Parsing)
+  #     *   [Options for Generating](#class-CSV-label-Options+for+Generating)
+  #
+  #     For performance reasons, the options cannot be overridden in a CSV object,
+  #     so those specified here will endure.
+  #
+  #
+  # In addition to the CSV instance methods, several IO methods are delegated. See
+  # [Delegated Methods](#class-CSV-label-Delegated+Methods).
+  #
+  # ---
+  #
+  # Create a CSV object from a String object:
+  #     csv = CSV.new('foo,0')
+  #     csv # => #<CSV io_type:StringIO encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
+  #
+  # Create a CSV object from a File object:
+  #     File.write('t.csv', 'foo,0')
+  #     csv = CSV.new(File.open('t.csv'))
+  #     csv # => #<CSV io_type:File io_path:"t.csv" encoding:UTF-8 lineno:0 col_sep:"," row_sep:"\n" quote_char:"\"">
+  #
+  # ---
+  #
+  # Raises an exception if the argument is `nil`:
+  #     # Raises ArgumentError (Cannot parse nil as CSV):
+  #     CSV.new(nil)
+  #
   def initialize: (?String | IO | StringIO io, ?::Hash[Symbol, untyped] options) -> void
 
-  # This method can be used to easily parse CSV out of a String. You may either
-  # provide a `block` which will be called with each row of the String in turn, or
-  # just use the returned Array of Arrays (when no `block` is given).
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - parse(string) -> array_of_arrays
+  #   - parse(io) -> array_of_arrays
+  #   - parse(string, headers: ..., **options) -> csv_table
+  #   - parse(io, headers: ..., **options) -> csv_table
+  #   - parse(string, **options) {|row| ... }
+  #   - parse(io, **options) {|row| ... }
+  # -->
+  # Parses `string` or `io` using the specified `options`.
+  #
+  # *   Argument `string` should be a String object; it will be put into a new
+  #     StringIO object positioned at the beginning.
+  # *   Argument `io` should be an IO object that is:
+  #     *   Open for reading; on return, the IO object will be closed.
+  #     *   Positioned at the beginning. To position at the end, for appending,
+  #         use method CSV.generate. For any other positioning, pass a preset
+  #         StringIO object instead.
+  #
+  # *   Argument `options`: see [Options for
+  #     Parsing](#class-CSV-label-Options+for+Parsing)
+  #
+  #
+  # ###### Without Option `headers`
+  #
+  # Without {option `headers`[}](#class-CSV-label-Option+headers) case.
+  #
+  # These examples assume prior execution of:
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #
+  # ---
+  #
+  # With no block given, returns an Array of Arrays formed from the source.
+  #
+  # Parse a String:
+  #     a_of_a = CSV.parse(string)
+  #     a_of_a # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+  #
+  # Parse an open File:
+  #     a_of_a = File.open(path) do |file|
+  #       CSV.parse(file)
+  #     end
+  #     a_of_a # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+  #
+  # ---
+  #
+  # With a block given, calls the block with each parsed row:
   #
-  # You pass your `str` to read from, and an optional `options` containing
-  # anything CSV::new() understands.
+  # Parse a String:
+  #     CSV.parse(string) {|row| p row }
+  #
+  # Output:
+  #     ["foo", "0"]
+  #     ["bar", "1"]
+  #     ["baz", "2"]
+  #
+  # Parse an open File:
+  #     File.open(path) do |file|
+  #       CSV.parse(file) {|row| p row }
+  #     end
+  #
+  # Output:
+  #     ["foo", "0"]
+  #     ["bar", "1"]
+  #     ["baz", "2"]
+  #
+  # ###### With Option `headers`
+  #
+  # With {option `headers`[}](#class-CSV-label-Option+headers) case.
+  #
+  # These examples assume prior execution of:
+  #     string = "Name,Count\nfoo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #
+  # ---
+  #
+  # With no block given, returns a CSV::Table object formed from the source.
+  #
+  # Parse a String:
+  #     csv_table = CSV.parse(string, headers: ['Name', 'Count'])
+  #     csv_table # => #<CSV::Table mode:col_or_row row_count:5>
+  #
+  # Parse an open File:
+  #     csv_table = File.open(path) do |file|
+  #       CSV.parse(file, headers: ['Name', 'Count'])
+  #     end
+  #     csv_table # => #<CSV::Table mode:col_or_row row_count:4>
+  #
+  # ---
+  #
+  # With a block given, calls the block with each parsed row, which has been
+  # formed into a CSV::Row object:
+  #
+  # Parse a String:
+  #     CSV.parse(string, headers: ['Name', 'Count']) {|row| p row }
+  #
+  # Output:
+  #     # <CSV::Row "Name":"foo" "Count":"0">
+  #     # <CSV::Row "Name":"bar" "Count":"1">
+  #     # <CSV::Row "Name":"baz" "Count":"2">
+  #
+  # Parse an open File:
+  #     File.open(path) do |file|
+  #       CSV.parse(file, headers: ['Name', 'Count']) {|row| p row }
+  #     end
+  #
+  # Output:
+  #     # <CSV::Row "Name":"foo" "Count":"0">
+  #     # <CSV::Row "Name":"bar" "Count":"1">
+  #     # <CSV::Row "Name":"baz" "Count":"2">
+  #
+  # ---
+  #
+  # Raises an exception if the argument is not a String object or IO object:
+  #     # Raises NoMethodError (undefined method `close' for :foo:Symbol)
+  #     CSV.parse(:foo)
   #
   def self.parse: (String str, ?::Hash[Symbol, untyped] options) ?{ (::Array[String?] arg0) -> void } -> ::Array[::Array[String?]]?
 
-  # This method is a shortcut for converting a single line of a CSV String into an
-  # Array. Note that if `line` contains multiple rows, anything beyond the first
-  # row is ignored.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - CSV.parse_line(string) -> new_array or nil
+  #   - CSV.parse_line(io) -> new_array or nil
+  #   - CSV.parse_line(string, **options) -> new_array or nil
+  #   - CSV.parse_line(io, **options) -> new_array or nil
+  #   - CSV.parse_line(string, headers: true, **options) -> csv_row or nil
+  #   - CSV.parse_line(io, headers: true, **options) -> csv_row or nil
+  # -->
+  # Returns the data created by parsing the first line of `string` or `io` using
+  # the specified `options`.
+  #
+  # *   Argument `string` should be a String object; it will be put into a new
+  #     StringIO object positioned at the beginning.
+  # *   Argument `io` should be an IO object that is:
+  #     *   Open for reading; on return, the IO object will be closed.
+  #     *   Positioned at the beginning. To position at the end, for appending,
+  #         use method CSV.generate. For any other positioning, pass a preset
+  #         StringIO object instead.
+  #
+  # *   Argument `options`: see [Options for
+  #     Parsing](#class-CSV-label-Options+for+Parsing)
+  #
+  #
+  # ###### Without Option `headers`
+  #
+  # Without option `headers`, returns the first row as a new Array.
+  #
+  # These examples assume prior execution of:
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #
+  # Parse the first line from a String object:
+  #     CSV.parse_line(string) # => ["foo", "0"]
   #
-  # The `options` parameter can be anything CSV::new() understands.
+  # Parse the first line from a File object:
+  #     File.open(path) do |file|
+  #       CSV.parse_line(file) # => ["foo", "0"]
+  #     end # => ["foo", "0"]
+  #
+  # Returns `nil` if the argument is an empty String:
+  #     CSV.parse_line('') # => nil
+  #
+  # ###### With Option `headers`
+  #
+  # With {option `headers`[}](#class-CSV-label-Option+headers), returns the first
+  # row as a CSV::Row object.
+  #
+  # These examples assume prior execution of:
+  #     string = "Name,Count\nfoo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #
+  # Parse the first line from a String object:
+  #     CSV.parse_line(string, headers: true) # => #<CSV::Row "Name":"foo" "Count":"0">
+  #
+  # Parse the first line from a File object:
+  #     File.open(path) do |file|
+  #       CSV.parse_line(file, headers: true)
+  #     end # => #<CSV::Row "Name":"foo" "Count":"0">
+  #
+  # ---
+  #
+  # Raises an exception if the argument is `nil`:
+  #     # Raises ArgumentError (Cannot parse nil as CSV):
+  #     CSV.parse_line(nil)
   #
   def self.parse_line: (String str, ?::Hash[Symbol, untyped] options) -> ::Array[String?]?
 
-  # Slurps the remaining rows and returns an Array of Arrays.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - csv.read -> array or csv_table
+  # -->
+  # Forms the remaining rows from `self` into:
+  # *   A CSV::Table object, if headers are in use.
+  # *   An Array of Arrays, otherwise.
+  #
+  #
+  # The data source must be opened for reading.
+  #
+  # Without headers:
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #     csv = CSV.open(path)
+  #     csv.read # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+  #
+  # With headers:
+  #     string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #     csv = CSV.open(path, headers: true)
+  #     csv.read # => #<CSV::Table mode:col_or_row row_count:4>
   #
-  # The data source must be open for reading.
+  # ---
+  #
+  # Raises an exception if the source is not opened for reading:
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     csv = CSV.new(string)
+  #     csv.close
+  #     # Raises IOError (not opened for reading)
+  #     csv.read
   #
   def read: () -> ::Array[::Array[String?]]
 
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - readline()
+  # -->
+  #
   def readline: () -> ::Array[String?]?
 
-  # Use to slurp a CSV file into an Array of Arrays. Pass the `path` to the file
-  # and any `options` CSV::new() understands. This method also understands an
-  # additional `:encoding` parameter that you can use to specify the Encoding of
-  # the data in the file to be read. You must provide this unless your data is in
-  # Encoding::default_external(). CSV will use this to determine how to parse the
-  # data. You may provide a second Encoding to have the data transcoded as it is
-  # read. For example, `encoding: "UTF-32BE:UTF-8"` would read UTF-32BE data from
-  # the file but transcode it to UTF-8 before CSV parses it.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - read(source, **options) -> array_of_arrays
+  #   - read(source, headers: true, **options) -> csv_table
+  # -->
+  # Opens the given `source` with the given `options` (see CSV.open), reads the
+  # source (see CSV#read), and returns the result, which will be either an Array
+  # of Arrays or a CSV::Table.
+  #
+  # Without headers:
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #     CSV.read(path) # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+  #
+  # With headers:
+  #     string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #     CSV.read(path, headers: true) # => #<CSV::Table mode:col_or_row row_count:4>
   #
   def self.read: (String path, ?::Hash[Symbol, untyped] options) -> ::Array[::Array[String?]]
 
-  # The primary write method for wrapped Strings and IOs, `row` (an Array or
-  # CSV::Row) is converted to CSV and appended to the data source. When a CSV::Row
-  # is passed, only the row's fields() are appended to the output.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - csv << row -> self
+  # -->
+  # Appends a row to `self`.
   #
-  # The data source must be open for writing.
+  # *   Argument `row` must be an Array object or a CSV::Row object.
+  # *   The output stream must be open for writing.
+  #
+  #
+  # ---
+  #
+  # Append Arrays:
+  #     CSV.generate do |csv|
+  #       csv << ['foo', 0]
+  #       csv << ['bar', 1]
+  #       csv << ['baz', 2]
+  #     end # => "foo,0\nbar,1\nbaz,2\n"
+  #
+  # Append CSV::Rows:
+  #     headers = []
+  #     CSV.generate do |csv|
+  #       csv << CSV::Row.new(headers, ['foo', 0])
+  #       csv << CSV::Row.new(headers, ['bar', 1])
+  #       csv << CSV::Row.new(headers, ['baz', 2])
+  #     end # => "foo,0\nbar,1\nbaz,2\n"
+  #
+  # Headers in CSV::Row objects are not appended:
+  #     headers = ['Name', 'Count']
+  #     CSV.generate do |csv|
+  #       csv << CSV::Row.new(headers, ['foo', 0])
+  #       csv << CSV::Row.new(headers, ['bar', 1])
+  #       csv << CSV::Row.new(headers, ['baz', 2])
+  #     end # => "foo,0\nbar,1\nbaz,2\n"
+  #
+  # ---
+  #
+  # Raises an exception if `row` is not an Array or CSV::Row:
+  #     CSV.generate do |csv|
+  #       # Raises NoMethodError (undefined method `collect' for :foo:Symbol)
+  #       csv << :foo
+  #     end
+  #
+  # Raises an exception if the output stream is not opened for writing:
+  #     path = 't.csv'
+  #     File.write(path, '')
+  #     File.open(path) do |file|
+  #       CSV.open(file) do |csv|
+  #         # Raises IOError (not opened for writing)
+  #         csv << ['foo', 0]
+  #       end
+  #     end
   #
   def <<: (::Array[untyped] | CSV::Row row) -> void
 
-  # This method wraps a String you provide, or an empty default String, in a CSV
-  # object which is passed to the provided block. You can use the block to append
-  # CSV rows to the String and when the block exits, the final String will be
-  # returned.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - generate(csv_string, **options) {|csv| ... }
+  #   - generate(**options) {|csv| ... }
+  # -->
+  # *   Argument `csv_string`, if given, must be a String object; defaults to a
+  #     new empty String.
+  # *   Arguments `options`, if given, should be generating options. See [Options
+  #     for Generating](#class-CSV-label-Options+for+Generating).
+  #
   #
-  # Note that a passed String **is** modified by this method. Call dup() before
-  # passing if you need a new String.
+  # ---
+  #
+  # Creates a new CSV object via `CSV.new(csv_string, **options)`; calls the block
+  # with the CSV object, which the block may modify; returns the String generated
+  # from the CSV object.
+  #
+  # Note that a passed String **is** modified by this method. Pass
+  # `csv_string`.dup if the String must be preserved.
+  #
+  # This method has one additional option: `:encoding`, which sets the base
+  # Encoding for the output if no no `str` is specified. CSV needs this hint if
+  # you plan to output non-ASCII compatible data.
+  #
+  # ---
+  #
+  # Add lines:
+  #     input_string = "foo,0\nbar,1\nbaz,2\n"
+  #     output_string = CSV.generate(input_string) do |csv|
+  #       csv << ['bat', 3]
+  #       csv << ['bam', 4]
+  #     end
+  #     output_string # => "foo,0\nbar,1\nbaz,2\nbat,3\nbam,4\n"
+  #     input_string # => "foo,0\nbar,1\nbaz,2\nbat,3\nbam,4\n"
+  #     output_string.equal?(input_string) # => true # Same string, modified
+  #
+  # Add lines into new string, preserving old string:
+  #     input_string = "foo,0\nbar,1\nbaz,2\n"
+  #     output_string = CSV.generate(input_string.dup) do |csv|
+  #       csv << ['bat', 3]
+  #       csv << ['bam', 4]
+  #     end
+  #     output_string # => "foo,0\nbar,1\nbaz,2\nbat,3\nbam,4\n"
+  #     input_string # => "foo,0\nbar,1\nbaz,2\n"
+  #     output_string.equal?(input_string) # => false # Different strings
+  #
+  # Create lines from nothing:
+  #     output_string = CSV.generate do |csv|
+  #       csv << ['foo', 0]
+  #       csv << ['bar', 1]
+  #       csv << ['baz', 2]
+  #     end
+  #     output_string # => "foo,0\nbar,1\nbaz,2\n"
+  #
+  # ---
   #
-  # The `options` parameter can be anything CSV::new() understands.  This method
-  # understands an additional `:encoding` parameter when not passed a String to
-  # set the base Encoding for the output.  CSV needs this hint if you plan to
-  # output non-ASCII compatible data.
+  # Raises an exception if `csv_string` is not a String object:
+  #     # Raises TypeError (no implicit conversion of Integer into String)
+  #     CSV.generate(0)
   #
   def self.generate: (?String str, **untyped options) { (CSV csv) -> void } -> String
 
-  # :call-seq:
-  #   csv.each -> enumerator
-  #   csv.each {|row| ...}
-  #
-  # Calls the block with each successive row.
-  # The data source must be opened for reading.
+  # <!--
+  #   rdoc-file=lib/csv.rb
+  #   - csv.each -> enumerator
+  #   - csv.each {|row| ...}
+  # -->
+  # Calls the block with each successive row. The data source must be opened for
+  # reading.
   #
   # Without headers:
-  #   string = "foo,0\nbar,1\nbaz,2\n"
-  #   csv = CSV.new(string)
-  #   csv.each do |row|
-  #     p row
-  #   end
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     csv = CSV.new(string)
+  #     csv.each do |row|
+  #       p row
+  #     end
+  #
   # Output:
-  #   ["foo", "0"]
-  #   ["bar", "1"]
-  #   ["baz", "2"]
+  #     ["foo", "0"]
+  #     ["bar", "1"]
+  #     ["baz", "2"]
   #
   # With headers:
-  #   string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
-  #   csv = CSV.new(string, headers: true)
-  #   csv.each do |row|
-  #     p row
-  #   end
+  #     string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     csv = CSV.new(string, headers: true)
+  #     csv.each do |row|
+  #       p row
+  #     end
+  #
   # Output:
-  #   <CSV::Row "Name":"foo" "Value":"0">
-  #   <CSV::Row "Name":"bar" "Value":"1">
-  #   <CSV::Row "Name":"baz" "Value":"2">
+  #     <CSV::Row "Name":"foo" "Value":"0">
+  #     <CSV::Row "Name":"bar" "Value":"1">
+  #     <CSV::Row "Name":"baz" "Value":"2">
   #
   # ---
   #
   # Raises an exception if the source is not opened for reading:
-  #   string = "foo,0\nbar,1\nbaz,2\n"
-  #   csv = CSV.new(string)
-  #   csv.close
-  #   # Raises IOError (not opened for reading)
-  #   csv.each do |row|
-  #     p row
-  #   end
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     csv = CSV.new(string)
+  #     csv.close
+  #     # Raises IOError (not opened for reading)
+  #     csv.each do |row|
+  #       p row
+  #     end
+  #
   def each: () -> Enumerator[untyped, Integer]
           | () { (untyped) -> void } -> Integer
-
 end
 
-# The options used when no overrides are given by calling code. They are:
-#
-# **`:col_sep`**
-# :   `","`
-# **`:row_sep`**
-# :   `:auto`
-# **`:quote_char`**
-# :   `'"'`
-# **`:field_size_limit`**
-# :   `nil`
-# **`:converters`**
-# :   `nil`
-# **`:unconverted_fields`**
-# :   `nil`
-# **`:headers`**
-# :   `false`
-# **`:return_headers`**
-# :   `false`
-# **`:header_converters`**
-# :   `nil`
-# **`:skip_blanks`**
-# :   `false`
-# **`:force_quotes`**
-# :   `false`
-# **`:skip_lines`**
-# :   `nil`
-# **`:liberal_parsing`**
-# :   `false`
-# **`:quote_empty`**
-# :   `true`
-#
+# <!-- rdoc-file=lib/csv.rb -->
+# Default values for method options.
 #
 CSV::DEFAULT_OPTIONS: ::Hash[untyped, untyped]
 
+# <!-- rdoc-file=lib/csv/version.rb -->
 # The version of the installed library.
 #
 CSV::VERSION: String
 
+# <!-- rdoc-file=lib/csv/row.rb -->
 # A CSV::Row is part Array and part Hash. It retains an order for the fields and
 # allows duplicates just as an Array would, but also allows you to access fields
 # by name just as you could if they were in a Hash.
@@ -454,52 +2261,189 @@ class CSV::Row < Object
   include Enumerable[Array[String]]
   extend Forwardable
 
-  # If a two-element Array is provided, it is assumed to be a header and field and
-  # the pair is appended. A Hash works the same way with the key being the header
-  # and the value being the field. Anything else is assumed to be a lone field
-  # which is appended with a `nil` header.
-  #
-  # This method returns the row for chaining.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row << [header, value] -> self
+  #   - row << hash -> self
+  #   - row << value -> self
+  # -->
+  # Adds a field to `self`; returns `self`:
+  #
+  # If the argument is a 2-element Array `[header, value]`, a field is added with
+  # the given `header` and `value`:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row << ['NAME', 'Bat']
+  #     row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" "NAME":"Bat">
+  #
+  # If the argument is a Hash, each `key-value` pair is added as a field with
+  # header `key` and value `value`.
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row << {NAME: 'Bat', name: 'Bam'}
+  #     row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" NAME:"Bat" name:"Bam">
+  #
+  # Otherwise, the given `value` is added as a field with no header.
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row << 'Bag'
+  #     row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" nil:"Bag">
   #
   def <<: (untyped arg) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - ==(other)
+  # -->
   # Returns `true` if this row contains the same headers and fields in the same
   # order as `other`.
   #
   def ==: (untyped other) -> bool
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - [](header_or_index, minimum_index = 0)
+  # -->
+  #
   alias [] field
 
-  # Looks up the field by the semantics described in CSV::Row.field() and assigns
-  # the `value`.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row[index] = value -> value
+  #   - row[header, offset] = value -> value
+  #   - row[header] = value -> value
+  # -->
+  # Assigns the field value for the given `index` or `header`; returns `value`.
+  #
+  # ---
+  #
+  # Assign field value by Integer index:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row[0] = 'Bat'
+  #     row[1] = 3
+  #     row # => #<CSV::Row "Name":"Bat" "Value":3>
+  #
+  # Counts backward from the last column if `index` is negative:
+  #     row[-1] = 4
+  #     row[-2] = 'Bam'
+  #     row # => #<CSV::Row "Name":"Bam" "Value":4>
+  #
+  # Extends the row with `nil:nil` if positive `index` is not in the row:
+  #     row[4] = 5
+  #     row # => #<CSV::Row "Name":"bad" "Value":4 nil:nil nil:nil nil:5>
+  #
+  # Raises IndexError if negative `index` is too small (too far from zero).
   #
-  # Assigning past the end of the row with an index will set all pairs between to
-  # `[nil, nil]`. Assigning to an unused header appends the new pair.
+  # ---
+  #
+  # Assign field value by header (first found):
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row['Name'] = 'Bat'
+  #     row # => #<CSV::Row "Name":"Bat" "Name":"Bar" "Name":"Baz">
+  #
+  # Assign field value by header, ignoring `offset` leading fields:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row['Name', 2] = 4
+  #     row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":4>
+  #
+  # Append new field by (new) header:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row['New'] = 6
+  #     row# => #<CSV::Row "Name":"foo" "Value":"0" "New":6>
   #
   def []=: (*untyped args) -> untyped
 
-  # Removes a pair from the row by `header` or `index`. The pair is located as
-  # described in CSV::Row.field(). The deleted pair is returned, or `nil` if a
-  # pair could not be found.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - delete(index) -> [header, value] or nil
+  #   - delete(header) -> [header, value] or empty_array
+  #   - delete(header, offset) -> [header, value] or empty_array
+  # -->
+  # Removes a specified field from `self`; returns the 2-element Array `[header,
+  # value]` if the field exists.
+  #
+  # If an Integer argument `index` is given, removes and returns the field at
+  # offset `index`, or returns `nil` if the field does not exist:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.delete(1) # => ["Name", "Bar"]
+  #     row.delete(50) # => nil
+  #
+  # Otherwise, if the single argument `header` is given, removes and returns the
+  # first-found field with the given header, of returns a new empty Array if the
+  # field does not exist:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.delete('Name') # => ["Name", "Foo"]
+  #     row.delete('NAME') # => []
+  #
+  # If argument `header` and Integer argument `offset` are given, removes and
+  # returns the first-found field with the given header whose `index` is at least
+  # as large as `offset`:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.delete('Name', 1) # => ["Name", "Bar"]
+  #     row.delete('NAME', 1) # => []
   #
   def delete: (untyped header_or_index, ?untyped minimum_index) -> untyped
 
-  # The provided `block` is passed a header and field for each pair in the row and
-  # expected to return `true` or `false`, depending on whether the pair should be
-  # deleted.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.delete_if {|header, value| ... } -> self
+  # -->
+  # Removes fields from `self` as selected by the block; returns `self`.
   #
-  # This method returns the row for chaining.
+  # Removes each field for which the block returns a truthy value:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.delete_if {|header, value| value.start_with?('B') } # => true
+  #     row # => #<CSV::Row "Name":"Foo">
+  #     row.delete_if {|header, value| header.start_with?('B') } # => false
   #
-  # If no block is given, an Enumerator is returned.
+  # If no block is given, returns a new Enumerator:
+  #     row.delete_if # => #<Enumerator: #<CSV::Row "Name":"Foo">:delete_if>
   #
   def delete_if: () { (*untyped) -> untyped } -> untyped
 
-  # Extracts the nested value specified by the sequence of `index` or `header`
-  # objects by calling dig at each step, returning nil if any intermediate step is
-  # nil.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.dig(index_or_header, *identifiers) -> object
+  # -->
+  # Finds and returns the object in nested object that is specified by
+  # `index_or_header` and `specifiers`.
+  #
+  # The nested objects may be instances of various classes. See [Dig
+  # Methods](https://docs.ruby-lang.org/en/master/doc/dig_methods_rdoc.html).
+  #
+  # Examples:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.dig(1) # => "0"
+  #     row.dig('Value') # => "0"
+  #     row.dig(5) # => nil
   #
   def dig: (untyped index_or_header, *untyped indexes) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - each(&block)
+  # -->
   # Yields each pair of the row as header and field tuples (much like iterating
   # over a Hash). This method returns the row for chaining.
   #
@@ -510,112 +2454,326 @@ class CSV::Row < Object
   def each: () -> Enumerator[Array[String], self]
           | () { (Array[String]) -> void } -> self
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - each_pair(&block)
+  # -->
+  #
   alias each_pair each
 
   def empty?: (*untyped args) { (*untyped) -> untyped } -> bool
 
-  # This method will fetch the field value by `header`. It has the same behavior
-  # as Hash#fetch: if there is a field with the given `header`, its value is
-  # returned. Otherwise, if a block is given, it is yielded the `header` and its
-  # result is returned; if a `default` is given as the second argument, it is
-  # returned; otherwise a KeyError is raised.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - fetch(header)
+  #   - fetch(header, default)
+  #   - fetch(header) {|row| ... }
+  # -->
+  # Returns the field value as specified by `header`.
+  #
+  # ---
+  #
+  # With the single argument `header`, returns the field value for that header
+  # (first found):
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.fetch('Name') # => "Foo"
+  #
+  # Raises exception `KeyError` if the header does not exist.
+  #
+  # ---
+  #
+  # With arguments `header` and `default` given, returns the field value for the
+  # header (first found) if the header exists, otherwise returns `default`:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.fetch('Name', '') # => "Foo"
+  #     row.fetch(:nosuch, '') # => ""
+  #
+  # ---
+  #
+  # With argument `header` and a block given, returns the field value for the
+  # header (first found) if the header exists; otherwise calls the block and
+  # returns its return value:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.fetch('Name') {|header| fail 'Cannot happen' } # => "Foo"
+  #     row.fetch(:nosuch) {|header| "Header '#{header} not found'" } # => "Header 'nosuch not found'"
   #
   def fetch: (untyped header, *untyped varargs) ?{ (*untyped) -> untyped } -> untyped
 
-  # This method will return the field value by `header` or `index`. If a field is
-  # not found, `nil` is returned.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - field(index)
+  #   - field(header)
+  #   - field(header, offset)
+  # -->
+  # Returns the field value for the given `index` or `header`.
+  #
+  # ---
+  #
+  # Fetch field value by Integer index:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.field(0) # => "foo"
+  #     row.field(1) # => "bar"
+  #
+  # Counts backward from the last column if `index` is negative:
+  #     row.field(-1) # => "0"
+  #     row.field(-2) # => "foo"
+  #
+  # Returns `nil` if `index` is out of range:
+  #     row.field(2) # => nil
+  #     row.field(-3) # => nil
   #
-  # When provided, `offset` ensures that a header match occurs on or later than
-  # the `offset` index. You can use this to find duplicate headers, without
-  # resorting to hard-coding exact indices.
+  # ---
+  #
+  # Fetch field value by header (first found):
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.field('Name') # => "Foo"
+  #
+  # Fetch field value by header, ignoring `offset` leading fields:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.field('Name', 2) # => "Baz"
+  #
+  # Returns `nil` if the header does not exist.
   #
   def field: (untyped header_or_index, ?untyped minimum_index) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - field?(data)
+  # -->
   # Returns `true` if `data` matches a field in this row, and `false` otherwise.
   #
   def field?: (untyped data) -> bool
 
-  # Returns `true` if this is a field row.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.field_row? -> true or false
+  # -->
+  # Returns `true` if this is a field row, `false` otherwise.
   #
   def field_row?: () -> bool
 
-  # This method accepts any number of arguments which can be headers, indices,
-  # Ranges of either, or two-element Arrays containing a header and offset. Each
-  # argument will be replaced with a field lookup as described in
-  # CSV::Row.field().
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - self.fields(*specifiers)
+  # -->
+  # Returns field values per the given `specifiers`, which may be any mixture of:
+  # *   Integer index.
+  # *   Range of Integer indexes.
+  # *   2-element Array containing a header and offset.
+  # *   Header.
+  # *   Range of headers.
+  #
+  #
+  # For `specifier` in one of the first four cases above, returns the result of
+  # `self.field(specifier)`;  see #field.
+  #
+  # Although there may be any number of `specifiers`, the examples here will
+  # illustrate one at a time.
   #
-  # If called with no arguments, all fields are returned.
+  # When the specifier is an Integer `index`, returns `self.field(index)`L
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.fields(1) # => ["Bar"]
+  #
+  # When the specifier is a Range of Integers `range`, returns
+  # `self.field(range)`:
+  #     row.fields(1..2) # => ["Bar", "Baz"]
+  #
+  # When the specifier is a 2-element Array `array`, returns `self.field(array)`L
+  #     row.fields('Name', 1) # => ["Foo", "Bar"]
+  #
+  # When the specifier is a header `header`, returns `self.field(header)`L
+  #     row.fields('Name') # => ["Foo"]
+  #
+  # When the specifier is a Range of headers `range`, forms a new Range
+  # `new_range` from the indexes of `range.start` and `range.end`, and returns
+  # `self.field(new_range)`:
+  #     source = "Name,NAME,name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.fields('Name'..'NAME') # => ["Foo", "Bar"]
+  #
+  # Returns all fields if no argument given:
+  #     row.fields # => ["Foo", "Bar", "Baz"]
   #
   def fields: (*untyped headers_and_or_indices) -> untyped
 
-  # Returns `true` if there is a field with the given `header`.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.has_key?(header)
+  # -->
+  # Returns `true` if there is a field with the given `header`, `false` otherwise.
   #
   def has_key?: (untyped header) -> bool
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - header?(header)
+  # -->
+  #
   alias header? has_key?
 
-  # Returns `true` if this is a header row.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.header_row? -> true or false
+  # -->
+  # Returns `true` if this is a header row, `false` otherwise.
   #
   def header_row?: () -> bool
 
-  # Returns the headers of this row.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.headers
+  # -->
+  # Returns the headers for this row:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table.first
+  #     row.headers # => ["Name", "Value"]
   #
   def headers: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - include?(header)
+  # -->
+  #
   alias include? has_key?
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - index( header )
+  #   - index( header, offset )
+  # -->
   # This method will return the index of a field with the provided `header`. The
   # `offset` can be used to locate duplicate header names, as described in
   # CSV::Row.field().
   #
   def index: (untyped header, ?untyped minimum_index) -> untyped
 
-  # A summary of fields, by header, in an ASCII compatible String.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.inspect -> string
+  # -->
+  # Returns an ASCII-compatible String showing:
+  # *   Class CSV::Row.
+  # *   Header-value pairs.
+  #
+  # Example:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.inspect # => "#<CSV::Row \"Name\":\"foo\" \"Value\":\"0\">"
   #
   def inspect: () -> String
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - key?(header)
+  # -->
+  #
   alias key? has_key?
 
   def length: (*untyped args) { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - member?(header)
+  # -->
+  #
   alias member? has_key?
 
-  # A shortcut for appending multiple fields. Equivalent to:
-  #
-  #     args.each { |arg| csv_row << arg }
-  #
-  # This method returns the row for chaining.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.push(*values) ->self
+  # -->
+  # Appends each of the given `values` to `self` as a field; returns `self`:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.push('Bat', 'Bam')
+  #     row # => #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz" nil:"Bat" nil:"Bam">
   #
   def push: (*untyped args) -> untyped
 
   def size: (*untyped args) { (*untyped) -> untyped } -> untyped
 
-  # Returns the row as a CSV String. Headers are not used. Equivalent to:
-  #
-  #     csv_row.fields.to_csv( options )
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.to_csv -> csv_string
+  # -->
+  # Returns the row as a CSV String. Headers are not included:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.to_csv # => "foo,0\n"
   #
   def to_csv: (**untyped) -> untyped
 
-  # Collapses the row into a simple Hash. Be warned that this discards field order
-  # and clobbers duplicate fields.
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - row.to_h -> hash
+  # -->
+  # Returns the new Hash formed by adding each header-value pair in `self` as a
+  # key-value pair in the Hash.
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.to_h # => {"Name"=>"foo", "Value"=>"0"}
+  #
+  # Header order is preserved, but repeated headers are ignored:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.to_h # => {"Name"=>"Foo"}
   #
   def to_h: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - to_hash()
+  # -->
+  #
   alias to_hash to_h
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - to_s(**options)
+  # -->
+  #
   alias to_s to_csv
 
+  # <!--
+  #   rdoc-file=lib/csv/row.rb
+  #   - values_at(*headers_and_or_indices)
+  # -->
+  #
   alias values_at fields
 end
 
 class CSV::FieldInfo < Struct[untyped]
 end
 
+# <!-- rdoc-file=lib/csv.rb -->
 # The error thrown when the parser encounters illegal CSV formatting.
 #
 class CSV::MalformedCSVError < RuntimeError
 end
 
+# <!-- rdoc-file=lib/csv/table.rb -->
 # A CSV::Table is a two-dimensional data structure for representing CSV
 # documents. Tables allow you to work with the data by row or column, manipulate
 # the data, and even convert the results back to CSV, if needed.
@@ -627,6 +2785,10 @@ class CSV::Table[out Elem] < Object
   include Enumerable[untyped]
   extend Forwardable
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - new(array_of_rows, headers: nil)
+  # -->
   # Constructs a new CSV::Table from `array_of_rows`, which are expected to be
   # CSV::Row objects. All rows are assumed to have the same headers.
   #
@@ -642,27 +2804,142 @@ class CSV::Table[out Elem] < Object
   #
   def initialize: (untyped array_of_rows, ?headers: untyped) -> untyped
 
-  # Adds a new row to the bottom end of this table. You can provide an Array,
-  # which will be converted to a CSV::Row (inheriting the table's headers()), or a
-  # CSV::Row.
-  #
-  # This method returns the table for chaining.
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - table << row_or_array -> self
+  # -->
+  # If `row_or_array` is a CSV::Row object, it is appended to the table:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table << CSV::Row.new(table.headers, ['bat', 3])
+  #     table[3] # => #<CSV::Row "Name":"bat" "Value":3>
+  #
+  # If `row_or_array` is an Array, it is used to create a new CSV::Row object
+  # which is then appended to the table:
+  #     table << ['bam', 4]
+  #     table[4] # => #<CSV::Row "Name":"bam" "Value":4>
   #
   def <<: (untyped row_or_array) -> untyped
 
-  # Returns `true` if all rows of this table ==() `other`'s rows.
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - ==(other)
+  # -->
+  # Returns `true` if all each row of `self` `==` the corresponding row of
+  # `other_table`, otherwise, `false`.
+  #
+  # The access mode does no affect the result.
+  #
+  # Equal tables:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     other_table = CSV.parse(source, headers: true)
+  #     table == other_table # => true
+  #
+  # Different row count:
+  #     other_table.delete(2)
+  #     table == other_table # => false
+  #
+  # Different last row:
+  #     other_table << ['bat', 3]
+  #     table == other_table # => false
   #
   def ==: (untyped other) -> bool
 
-  # In the default mixed mode, this method returns rows for index access and
-  # columns for header access. You can force the index association by first
-  # calling by_col!() or by_row!().
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - table[n] -> row
+  #   - table[range] -> array_of_rows
+  #   - table[header] -> array_of_fields
+  # -->
+  # Returns data from the table;  does not modify the table.
+  #
+  # ---
+  #
+  # The expression `table[n]`, where `n` is a non-negative Integer, returns the
+  # +n+th row of the table, if that row exists, and if the access mode is `:row`
+  # or `:col_or_row`:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+  #     table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+  #     table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+  #
+  # Counts backward from the last row if `n` is negative:
+  #     table[-1] # => #<CSV::Row "Name":"baz" "Value":"2">
+  #
+  # Returns `nil` if `n` is too large or too small:
+  #     table[4] # => nil
+  #     table[-4] => nil
+  #
+  # Raises an exception if the access mode is `:row` and `n` is not an
+  # [Integer-convertible
+  # object](https://docs.ruby-lang.org/en/master/implicit_conversion_rdoc.html#lab
+  # el-Integer-Convertible+Objects).
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     # Raises TypeError (no implicit conversion of String into Integer):
+  #     table['Name']
+  #
+  # ---
+  #
+  # The expression `table[range]`, where `range` is a Range object, returns rows
+  # from the table, beginning at row `range.first`, if those rows exist, and if
+  # the access mode is `:row` or `:col_or_row`:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     rows = table[1..2] # => #<CSV::Row "Name":"bar" "Value":"1">
+  #     rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+  #     table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+  #     rows = table[1..2] # => #<CSV::Row "Name":"bar" "Value":"1">
+  #     rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+  #
+  # If there are too few rows, returns all from `range.first` to the end:
+  #     rows = table[1..50] # => #<CSV::Row "Name":"bar" "Value":"1">
+  #     rows # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+  #
+  # Special case:  if `range.start == table.size`, returns an empty Array:
+  #     table[table.size..50] # => []
+  #
+  # If `range.end` is negative, calculates the ending index from the end:
+  #     rows = table[0..-1]
+  #     rows # => [#<CSV::Row "Name":"foo" "Value":"0">, #<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
   #
-  # Columns are returned as an Array of values.  Altering that Array has no effect
-  # on the table.
+  # If `range.start` is negative, calculates the starting index from the end:
+  #     rows = table[-1..2]
+  #     rows # => [#<CSV::Row "Name":"baz" "Value":"2">]
+  #
+  # If `range.start` is larger than `table.size`, returns `nil`:
+  #     table[4..4] # => nil
+  #
+  # ---
+  #
+  # The expression `table[header]`, where `header` is a String, returns column
+  # values (Array of Strings) if the column exists and if the access mode is
+  # `:col` or `:col_or_row`:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.by_col! # => #<CSV::Table mode:col row_count:4>
+  #     table['Name'] # => ["foo", "bar", "baz"]
+  #     table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+  #     col = table['Name']
+  #     col # => ["foo", "bar", "baz"]
+  #
+  # Modifying the returned column values does not modify the table:
+  #     col[0] = 'bat'
+  #     col # => ["bat", "bar", "baz"]
+  #     table['Name'] # => ["foo", "bar", "baz"]
+  #
+  # Returns an Array of `nil` values if there is no such column:
+  #     table['Nosuch'] # => [nil, nil, nil]
   #
   def []: (untyped index_or_header) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - []=(index_or_header, value)
+  # -->
   # In the default mixed mode, this method assigns rows for index access and
   # columns for header access. You can force the index association by first
   # calling by_col!() or by_row!().
@@ -680,6 +2957,10 @@ class CSV::Table[out Elem] < Object
   #
   def []=: (untyped index_or_header, untyped value) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - by_col()
+  # -->
   # Returns a duplicate table object, in column mode. This is handy for chaining
   # in a single call without changing the table mode, but be aware that this
   # method can consume a fair amount of memory for bigger data sets.
@@ -689,6 +2970,10 @@ class CSV::Table[out Elem] < Object
   #
   def by_col: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - by_col!()
+  # -->
   # Switches the mode of this table to column mode. All calls to indexing and
   # iteration methods will work with columns until the mode is changed again.
   #
@@ -696,6 +2981,10 @@ class CSV::Table[out Elem] < Object
   #
   def by_col!: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - by_col_or_row()
+  # -->
   # Returns a duplicate table object, in mixed mode. This is handy for chaining in
   # a single call without changing the table mode, but be aware that this method
   # can consume a fair amount of memory for bigger data sets.
@@ -705,6 +2994,10 @@ class CSV::Table[out Elem] < Object
   #
   def by_col_or_row: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - by_col_or_row!()
+  # -->
   # Switches the mode of this table to mixed mode. All calls to indexing and
   # iteration methods will use the default intelligent indexing system until the
   # mode is changed again. In mixed mode an index is assumed to be a row reference
@@ -714,6 +3007,10 @@ class CSV::Table[out Elem] < Object
   #
   def by_col_or_row!: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - by_row()
+  # -->
   # Returns a duplicate table object, in row mode.  This is handy for chaining in
   # a single call without changing the table mode, but be aware that this method
   # can consume a fair amount of memory for bigger data sets.
@@ -723,6 +3020,10 @@ class CSV::Table[out Elem] < Object
   #
   def by_row: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - by_row!()
+  # -->
   # Switches the mode of this table to row mode. All calls to indexing and
   # iteration methods will work with rows until the mode is changed again.
   #
@@ -730,36 +3031,121 @@ class CSV::Table[out Elem] < Object
   #
   def by_row!: () -> untyped
 
-  # Removes and returns the indicated columns or rows. In the default mixed mode
-  # indices refer to rows and everything else is assumed to be a column headers.
-  # Use by_col!() or by_row!() to force the lookup.
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - table.delete(*indexes) -> deleted_values
+  #   - table.delete(*headers) -> deleted_values
+  # -->
+  # If the access mode is `:row` or `:col_or_row`, and each argument is either an
+  # Integer or a Range, returns deleted rows. Otherwise, returns deleted columns
+  # data.
   #
-  def delete: (*untyped indexes_or_headers) -> untyped
-
-  # Removes any column or row for which the block returns `true`. In the default
-  # mixed mode or row mode, iteration is the standard row major walking of rows.
-  # In column mode, iteration will `yield` two element tuples containing the
-  # column name and an Array of values for that column.
+  # In either case, the returned values are in the order specified by the
+  # arguments.  Arguments may be repeated.
   #
-  # This method returns the table for chaining.
+  # ---
   #
-  # If no block is given, an Enumerator is returned.
+  # Returns rows as an Array of CSV::Row objects.
+  #
+  # One index:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     deleted_values = table.delete(0)
+  #     deleted_values # => [#<CSV::Row "Name":"foo" "Value":"0">]
+  #
+  # Two indexes:
+  #     table = CSV.parse(source, headers: true)
+  #     deleted_values = table.delete(2, 0)
+  #     deleted_values # => [#<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">]
+  #
+  # ---
+  #
+  # Returns columns data as column Arrays.
+  #
+  # One header:
+  #     table = CSV.parse(source, headers: true)
+  #     deleted_values = table.delete('Name')
+  #     deleted_values # => ["foo", "bar", "baz"]
+  #
+  # Two headers:
+  #     table = CSV.parse(source, headers: true)
+  #     deleted_values = table.delete('Value', 'Name')
+  #     deleted_values # => [["0", "1", "2"], ["foo", "bar", "baz"]]
+  #
+  def delete: (*untyped indexes_or_headers) -> untyped
+
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - delete_if() { |header, self| ... }
+  # -->
+  # Removes rows or columns for which the block returns a truthy value; returns
+  # `self`.
+  #
+  # Removes rows when the access mode is `:row` or `:col_or_row`; calls the block
+  # with each CSV::Row object:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     table.size # => 3
+  #     table.delete_if {|row| row['Name'].start_with?('b') }
+  #     table.size # => 1
+  #
+  # Removes columns when the access mode is `:col`; calls the block with each
+  # column as a 2-element array containing the header and an Array of column
+  # fields:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.by_col! # => #<CSV::Table mode:col row_count:4>
+  #     table.headers.size # => 2
+  #     table.delete_if {|column_data| column_data[1].include?('2') }
+  #     table.headers.size # => 1
+  #
+  # Returns a new Enumerator if no block is given:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.delete_if # => #<Enumerator: #<CSV::Table mode:col_or_row row_count:4>:delete_if>
   #
   def delete_if: () { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - dig(index_or_header, *index_or_headers)
+  # -->
   # Extracts the nested value specified by the sequence of `index` or `header`
   # objects by calling dig at each step, returning nil if any intermediate step is
   # nil.
   #
   def dig: (untyped index_or_header, *untyped index_or_headers) -> untyped
 
-  # In the default mixed mode or row mode, iteration is the standard row major
-  # walking of rows. In column mode, iteration will `yield` two element tuples
-  # containing the column name and an Array of values for that column.
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - each() { |header, self| ... }
+  # -->
+  # Calls the block with each row or column; returns `self`.
   #
-  # This method returns the table for chaining.
+  # When the access mode is `:row` or `:col_or_row`, calls the block with each
+  # CSV::Row object:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     table.each {|row| p row }
   #
-  # If no block is given, an Enumerator is returned.
+  # Output:
+  #     #<CSV::Row "Name":"foo" "Value":"0">
+  #     #<CSV::Row "Name":"bar" "Value":"1">
+  #     #<CSV::Row "Name":"baz" "Value":"2">
+  #
+  # When the access mode is `:col`, calls the block with each column as a
+  # 2-element array containing the header and an Array of column fields:
+  #     table.by_col! # => #<CSV::Table mode:col row_count:4>
+  #     table.each {|column_data| p column_data }
+  #
+  # Output:
+  #     ["Name", ["foo", "bar", "baz"]]
+  #     ["Value", ["0", "1", "2"]]
+  #
+  # Returns a new Enumerator if no block is given:
+  #     table.each # => #<Enumerator: #<CSV::Table mode:col row_count:4>:each>
   #
   def each: () -> Enumerator[untyped, self]
           | () { (untyped) -> void } -> self
@@ -767,37 +3153,65 @@ class CSV::Table[out Elem] < Object
 
   def empty?: (*untyped args) { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - headers()
+  # -->
   # Returns the headers for the first row of this table (assumed to match all
   # other rows). The headers Array passed to CSV::Table.new is returned for empty
   # tables.
   #
   def headers: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - inspect()
+  # -->
   # Shows the mode and size of this table in a US-ASCII String.
   #
   def inspect: () -> String
 
   def length: (*untyped args) { (*untyped) -> untyped } -> untyped
 
+  # <!-- rdoc-file=lib/csv/table.rb -->
   # The current access mode for indexing and iteration.
   #
   def mode: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - table.push(*rows_or_arrays) -> self
+  # -->
   # A shortcut for appending multiple rows. Equivalent to:
-  #
-  #     rows.each { |row| self << row }
-  #
-  # This method returns the table for chaining.
+  #     rows.each {|row| self << row }
+  #
+  # Each argument may be either a CSV::Row object or an Array:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     rows = [
+  #       CSV::Row.new(table.headers, ['bat', 3]),
+  #       ['bam', 4]
+  #     ]
+  #     table.push(*rows)
+  #     table[3..4] # => [#<CSV::Row "Name":"bat" "Value":3>, #<CSV::Row "Name":"bam" "Value":4>]
   #
   def push: (*untyped rows) -> untyped
 
   def size: (*untyped args) { (*untyped) -> untyped } -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - to_a()
+  # -->
   # Returns the table as an Array of Arrays. Headers will be the first row, then
   # all of the field rows will follow.
   #
   def to_a: () -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - to_csv(write_headers: true, **options)
+  # -->
   # Returns the table as a complete CSV String. Headers will be listed first, then
   # all of the field rows.
   #
@@ -806,15 +3220,65 @@ class CSV::Table[out Elem] < Object
   #
   def to_csv: (?write_headers: boolish, **untyped) -> untyped
 
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - to_s(write_headers: true, **options)
+  # -->
+  #
   alias to_s to_csv
 
-  # The mixed mode default is to treat a list of indices as row access, returning
-  # the rows indicated. Anything else is considered columnar access. For columnar
-  # access, the return set has an Array for each row with the values indicated by
-  # the headers in each Array. You can force column or row mode using by_col!() or
-  # by_row!().
+  # <!--
+  #   rdoc-file=lib/csv/table.rb
+  #   - table.values_at(*indexes) -> array_of_rows
+  #   - table.values_at(*headers) -> array_of_columns_data
+  # -->
+  # If the access mode is `:row` or `:col_or_row`, and each argument is either an
+  # Integer or a Range, returns rows. Otherwise, returns columns data.
+  #
+  # In either case, the returned values are in the order specified by the
+  # arguments.  Arguments may be repeated.
+  #
+  # ---
+  #
+  # Returns rows as an Array of CSV::Row objects.
+  #
+  # No argument:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.values_at # => []
+  #
+  # One index:
+  #     values = table.values_at(0)
+  #     values # => [#<CSV::Row "Name":"foo" "Value":"0">]
+  #
+  # Two indexes:
+  #     values = table.values_at(2, 0)
+  #     values # => [#<CSV::Row "Name":"baz" "Value":"2">, #<CSV::Row "Name":"foo" "Value":"0">]
+  #
+  # One Range:
+  #     values = table.values_at(1..2)
+  #     values # => [#<CSV::Row "Name":"bar" "Value":"1">, #<CSV::Row "Name":"baz" "Value":"2">]
+  #
+  # Ranges and indexes:
+  #     values = table.values_at(0..1, 1..2, 0, 2)
+  #     pp values
+  #
+  # Output:
+  #     [#<CSV::Row "Name":"foo" "Value":"0">,
+  #      #<CSV::Row "Name":"bar" "Value":"1">,
+  #      #<CSV::Row "Name":"bar" "Value":"1">,
+  #      #<CSV::Row "Name":"baz" "Value":"2">,
+  #      #<CSV::Row "Name":"foo" "Value":"0">,
+  #      #<CSV::Row "Name":"baz" "Value":"2">]
+  #
+  # ---
   #
-  # You cannot mix column and row access.
+  # Returns columns data as row Arrays, each consisting of the specified columns
+  # data for that row:
+  #     values = table.values_at('Name')
+  #     values # => [["foo"], ["bar"], ["baz"]]
+  #     values = table.values_at('Value', 'Name')
+  #     values # => [["0", "foo"], ["1", "bar"], ["2", "baz"]]
   #
   def values_at: (*untyped indices_or_headers) -> untyped
 end