rbs 2.8.0 → 2.8.1

data/stdlib/csv/0/csv.rbs

@@ -1,6 +1,18 @@
 # <!-- rdoc-file=lib/csv.rb -->
 # ## CSV
-# CSV (comma-separated variables) data is a text representation of a table:
+#
+# ### In a Hurry?
+#
+# If you are familiar with CSV data and have a particular task in mind, you may
+# want to go directly to the:
+# *   [Recipes for CSV](doc/csv/recipes/recipes_rdoc.html).
+#
+#
+# Otherwise, read on here, about the API: classes, methods, and constants.
+#
+# ### CSV Data
+#
+# CSV (comma-separated values) 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
@@ -249,7 +261,9 @@
 # *   `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.
+# *   `field_size_limit`: Specifies the maximum field size + 1 allowed.
+#     Deprecated since 3.2.3. Use `max_field_size` instead.
+# *   `max_field_size`: Specifies the maximum field size allowed.
 # *   `converters`: Specifies the field converters to be used.
 # *   `unconverted_fields`: Specifies whether unconverted fields are to be
 #     available.
@@ -1515,7 +1529,7 @@
 # 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.
+# header converter `:downcase`, which downcases each parsed header.
 #
 # *   Option `header_converters` with a singleton parsing method:
 #         string = "Name,Count\nFoo,0\n,Bar,1\nBaz,2"
@@ -1653,119 +1667,90 @@ class CSV < Object
 
   # <!--
   #   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
+  #   - foreach(path_or_io, mode='r', **options) {|row| ... )
+  #   - foreach(path_or_io, mode='r', **options) -> new_enumerator
   # -->
-  # Calls the block with each row read from source `path` or `io`.
+  # 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.
+  # Path input without headers:
   #
-  # *   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 }
+  #     in_path = 't.csv'
+  #     File.write(in_path, string)
+  #     CSV.foreach(in_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")>
+  # Path input with headers:
   #
-  # Issues a warning if an encoding is unsupported:
-  #     CSV.foreach(File.open(path), encoding: 'foo:bar') {|row| }
+  #     string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     in_path = 't.csv'
+  #     File.write(in_path, string)
+  #     CSV.foreach(in_path, headers: true) {|row| p row }
   #
   # Output:
-  #     warning: Unsupported encoding foo ignored
-  #     warning: Unsupported encoding bar ignored
   #
-  # ###### With Option `headers`
+  #     <CSV::Row "Name":"foo" "Value":"0">
+  #     <CSV::Row "Name":"bar" "Value":"1">
+  #     <CSV::Row "Name":"baz" "Value":"2">
   #
-  # With {option `headers`[}](#class-CSV-label-Option+headers), returns each row
-  # as a CSV::Row object.
+  # IO stream input without headers:
   #
-  # These examples assume prior execution of:
-  #     string = "Name,Count\nfoo,0\nbar,1\nbaz,2\n"
+  #     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, headers: true) {|row| p row }
+  #     File.open('t.csv') do |in_io|
+  #       CSV.foreach(in_io) {|row| p row }
+  #     end
   #
   # 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 }
+  #     ["foo", "0"]
+  #     ["bar", "1"]
+  #     ["baz", "2"]
+  #
+  # IO stream input with headers:
+  #
+  #     string = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #     File.open('t.csv') do |in_io|
+  #       CSV.foreach(in_io, 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">
   #
-  # ---
+  #     <CSV::Row "Name":"foo" "Value":"0">
+  #     <CSV::Row "Name":"bar" "Value":"1">
+  #     <CSV::Row "Name":"baz" "Value":"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| }
+  # With no block given, returns an Enumerator:
   #
-  # 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| }
+  #     string = "foo,0\nbar,1\nbaz,2\n"
+  #     path = 't.csv'
+  #     File.write(path, string)
+  #     CSV.foreach(path) # => #<Enumerator: CSV:foreach("t.csv", "r")>
+  #
+  # Arguments:
+  # *   Argument `path_or_io` must be a file path or an IO stream.
+  # *   Argument `mode`, if given, must be a File mode See [Open
+  #     Mode](https://ruby-doc.org/core/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'
   #
-  # Raises an exception if `mode` is invalid:
-  #     # Raises ArgumentError (invalid access mode nosuch):
-  #     CSV.foreach(path, 'nosuch') {|row| }
+  #     would read `UTF-32BE` data from the file but transcode it to `UTF-8`
+  #     before parsing.
   #
   def self.foreach: [U] (String | IO | StringIO path, ?::Hash[Symbol, U] options) { (::Array[String?] arg0) -> void } -> void
 
@@ -2250,12 +2235,80 @@ CSV::DEFAULT_OPTIONS: ::Hash[untyped, untyped]
 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.
+# # CSV::Row
+# A CSV::Row instance represents a CSV table row. (see [class
+# CSV](../CSV.html)).
+#
+# The instance may have:
+# *   Fields: each is an object, not necessarily a String.
+# *   Headers: each serves a key, and also need not be a String.
+#
+#
+# ### Instance Methods
+#
+# CSV::Row has three groups of instance methods:
+# *   Its own internally defined instance methods.
+# *   Methods included by module Enumerable.
+# *   Methods delegated to class Array.:
+#     *   Array#empty?
+#     *   Array#length
+#     *   Array#size
+#
+#
+#
+# ## Creating a CSV::Row Instance
+#
+# Commonly, a new CSV::Row instance is created by parsing CSV source that has
+# headers:
+#     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+#     table = CSV.parse(source, headers: true)
+#     table.each {|row| p row }
+#
+# Output:
+#     #<CSV::Row "Name":"foo" "Value":"0">
+#     #<CSV::Row "Name":"bar" "Value":"1">
+#     #<CSV::Row "Name":"baz" "Value":"2">
+#
+# You can also create a row directly. See ::new.
+#
+# ## Headers
+#
+# Like a CSV::Table, a CSV::Row has headers.
 #
-# All rows returned by CSV will be constructed from this class, if header row
-# processing is activated.
+# A CSV::Row that was created by parsing CSV source inherits its headers from
+# the table:
+#     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+#     table = CSV.parse(source, headers: true)
+#     row = table.first
+#     row.headers # => ["Name", "Value"]
+#
+# You can also create a new row with headers; like the keys in a Hash, the
+# headers need not be Strings:
+#     row = CSV::Row.new([:name, :value], ['foo', 0])
+#     row.headers # => [:name, :value]
+#
+# The new row retains its headers even if added to a table that has headers:
+#     table << row # => #<CSV::Table mode:col_or_row row_count:5>
+#     row.headers # => [:name, :value]
+#     row[:name] # => "foo"
+#     row['Name'] # => nil
+#
+# ## Accessing Fields
+#
+# You may access a field in a CSV::Row with either its Integer index
+# (Array-style) or its header (Hash-style).
+#
+# Fetch a field using method #[]:
+#     row = CSV::Row.new(['Name', 'Value'], ['foo', 0])
+#     row[1] # => 0
+#     row['Value'] # => 0
+#
+# Set a field using method #[]=:
+#     row = CSV::Row.new(['Name', 'Value'], ['foo', 0])
+#     row # => #<CSV::Row "Name":"foo" "Value":0>
+#     row[0] = 'bar'
+#     row['Value'] = 1
+#     row # => #<CSV::Row "Name":"bar" "Value":1>
 #
 class CSV::Row < Object
   include Enumerable[Array[String]]
@@ -2296,10 +2349,17 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - ==(other)
+  #   - row == other -> true or false
   # -->
-  # Returns `true` if this row contains the same headers and fields in the same
-  # order as `other`.
+  # Returns `true` if `other` is a /CSV::Row that has the same fields (headers and
+  # values) in the same order as `self`; otherwise returns `false`:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     other_row = table[0]
+  #     row == other_row # => true
+  #     other_row = table[1]
+  #     row == other_row # => false
   #
   def ==: (untyped other) -> bool
 
@@ -2428,7 +2488,7 @@ class CSV::Row < Object
   # `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).
+  # Methods](https://docs.ruby-lang.org/en/master/dig_methods_rdoc.html).
   #
   # Examples:
   #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
@@ -2442,14 +2502,21 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - each(&block)
+  #   - row.each {|header, value| ... } -> self
   # -->
-  # Yields each pair of the row as header and field tuples (much like iterating
-  # over a Hash). This method returns the row for chaining.
+  # Calls the block with each header-value pair; returns `self`:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.each {|header, value| p [header, value] }
   #
-  # If no block is given, an Enumerator is returned.
+  # Output:
+  #     ["Name", "Foo"]
+  #     ["Name", "Bar"]
+  #     ["Name", "Baz"]
   #
-  # Support for Enumerable.
+  # If no block is given, returns a new Enumerator:
+  #     row.each # => #<Enumerator: #<CSV::Row "Name":"Foo" "Name":"Bar" "Name":"Baz">:each>
   #
   def each: () -> Enumerator[Array[String], self]
           | () { (Array[String]) -> void } -> self
@@ -2465,9 +2532,9 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - fetch(header)
-  #   - fetch(header, default)
-  #   - fetch(header) {|row| ... }
+  #   - fetch(header) -> value
+  #   - fetch(header, default) -> value
+  #   - fetch(header) {|row| ... } -> value
   # -->
   # Returns the field value as specified by `header`.
   #
@@ -2507,9 +2574,9 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - field(index)
-  #   - field(header)
-  #   - field(header, offset)
+  #   - field(index) -> value
+  #   - field(header) -> value
+  #   - field(header, offset) -> value
   # -->
   # Returns the field value for the given `index` or `header`.
   #
@@ -2550,9 +2617,14 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - field?(data)
+  #   - row.field?(value) -> true or false
   # -->
-  # Returns `true` if `data` matches a field in this row, and `false` otherwise.
+  # Returns `true` if `value` is a field in this row, `false` otherwise:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.field?('Bar') # => true
+  #     row.field?('BAR') # => false
   #
   def field?: (untyped data) -> bool
 
@@ -2566,7 +2638,7 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - self.fields(*specifiers)
+  #   - self.fields(*specifiers) -> array_of_fields
   # -->
   # Returns field values per the given `specifiers`, which may be any mixture of:
   # *   Integer index.
@@ -2613,7 +2685,7 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - row.has_key?(header)
+  #   - row.has_key?(header) -> true or false
   # -->
   # Returns `true` if there is a field with the given `header`, `false` otherwise.
   #
@@ -2636,7 +2708,7 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - row.headers
+  #   - row.headers -> array_of_headers
   # -->
   # Returns the headers for this row:
   #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
@@ -2655,12 +2727,23 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - index( header )
-  #   - index( header, offset )
+  #   - index(header) -> index
+  #   - index(header, offset) -> index
   # -->
-  # 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().
+  # Returns the index for the given header, if it exists; otherwise returns `nil`.
+  #
+  # With the single argument `header`, returns the index of the first-found field
+  # with the given `header`:
+  #     source = "Name,Name,Name\nFoo,Bar,Baz\n"
+  #     table = CSV.parse(source, headers: true)
+  #     row = table[0]
+  #     row.index('Name') # => 0
+  #     row.index('NAME') # => nil
+  #
+  # With arguments `header` and `offset`, returns the index of the first-found
+  # field with given `header`, but ignoring the first `offset` fields:
+  #     row.index('Name', 1) # => 1
+  #     row.index('Name', 3) # => nil
   #
   def index: (untyped header, ?untyped minimum_index) -> untyped
 
@@ -2698,7 +2781,7 @@ class CSV::Row < Object
 
   # <!--
   #   rdoc-file=lib/csv/row.rb
-  #   - row.push(*values) ->self
+  #   - 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"
@@ -2774,12 +2857,149 @@ 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.
+# # CSV::Table
+# A CSV::Table instance represents CSV data. (see [class CSV](../CSV.html)).
+#
+# The instance may have:
+# *   Rows: each is a Table::Row object.
+# *   Headers: names for the columns.
+#
+#
+# ### Instance Methods
+#
+# CSV::Table has three groups of instance methods:
+# *   Its own internally defined instance methods.
+# *   Methods included by module Enumerable.
+# *   Methods delegated to class Array.:
+#     *   Array#empty?
+#     *   Array#length
+#     *   Array#size
+#
+#
+#
+# ## Creating a CSV::Table Instance
 #
-# All tables returned by CSV will be constructed from this class, if header row
-# processing is activated.
+# Commonly, a new CSV::Table instance is created by parsing CSV source using
+# headers:
+#     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+#     table = CSV.parse(source, headers: true)
+#     table.class # => CSV::Table
+#
+# You can also create an instance directly. See ::new.
+#
+# ## Headers
+#
+# If a table has headers, the headers serve as labels for the columns of data.
+# Each header serves as the label for its column.
+#
+# The headers for a CSV::Table object are stored as an Array of Strings.
+#
+# Commonly, headers are defined in the first row of CSV source:
+#     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+#     table = CSV.parse(source, headers: true)
+#     table.headers # => ["Name", "Value"]
+#
+# If no headers are defined, the Array is empty:
+#     table = CSV::Table.new([])
+#     table.headers # => []
+#
+# ## Access Modes
+#
+# CSV::Table provides three modes for accessing table data:
+# *   Row mode.
+# *   Column mode.
+# *   Mixed mode (the default for a new table).
+#
+#
+# The access mode for aCSV::Table instance affects the behavior of some of its
+# instance methods:
+# *   #[]
+# *   #[]=
+# *   #delete
+# *   #delete_if
+# *   #each
+# *   #values_at
+#
+#
+# ### Row Mode
+#
+# Set a table to row mode with method #by_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>
+#
+# Specify a single row by an Integer index:
+#     # Get a row.
+#     table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+#     # Set a row, then get it.
+#     table[1] = CSV::Row.new(['Name', 'Value'], ['bam', 3])
+#     table[1] # => #<CSV::Row "Name":"bam" "Value":3>
+#
+# Specify a sequence of rows by a Range:
+#     # Get rows.
+#     table[1..2] # => [#<CSV::Row "Name":"bam" "Value":3>, #<CSV::Row "Name":"baz" "Value":"2">]
+#     # Set rows, then get them.
+#     table[1..2] = [
+#       CSV::Row.new(['Name', 'Value'], ['bat', 4]),
+#       CSV::Row.new(['Name', 'Value'], ['bad', 5]),
+#     ]
+#     table[1..2] # => [["Name", #<CSV::Row "Name":"bat" "Value":4>], ["Value", #<CSV::Row "Name":"bad" "Value":5>]]
+#
+# ### Column Mode
+#
+# Set a table to column mode with method #by_col!:
+#     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>
+#
+# Specify a column by an Integer index:
+#     # Get a column.
+#     table[0]
+#     # Set a column, then get it.
+#     table[0] = ['FOO', 'BAR', 'BAZ']
+#     table[0] # => ["FOO", "BAR", "BAZ"]
+#
+# Specify a column by its String header:
+#     # Get a column.
+#     table['Name'] # => ["FOO", "BAR", "BAZ"]
+#     # Set a column, then get it.
+#     table['Name'] = ['Foo', 'Bar', 'Baz']
+#     table['Name'] # => ["Foo", "Bar", "Baz"]
+#
+# ### Mixed Mode
+#
+# In mixed mode, you can refer to either rows or columns:
+# *   An Integer index refers to a row.
+# *   A Range index refers to multiple rows.
+# *   A String index refers to a column.
+#
+#
+# Set a table to mixed mode with method #by_col_or_row!:
+#     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+#     table = CSV.parse(source, headers: true)
+#     table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+#
+# Specify a single row by an Integer index:
+#     # Get a row.
+#     table[1] # => #<CSV::Row "Name":"bar" "Value":"1">
+#     # Set a row, then get it.
+#     table[1] = CSV::Row.new(['Name', 'Value'], ['bam', 3])
+#     table[1] # => #<CSV::Row "Name":"bam" "Value":3>
+#
+# Specify a sequence of rows by a Range:
+#     # Get rows.
+#     table[1..2] # => [#<CSV::Row "Name":"bam" "Value":3>, #<CSV::Row "Name":"baz" "Value":"2">]
+#     # Set rows, then get them.
+#     table[1] = CSV::Row.new(['Name', 'Value'], ['bat', 4])
+#     table[2] = CSV::Row.new(['Name', 'Value'], ['bad', 5])
+#     table[1..2] # => [["Name", #<CSV::Row "Name":"bat" "Value":4>], ["Value", #<CSV::Row "Name":"bad" "Value":5>]]
+#
+# Specify a column by its String header:
+#     # Get a column.
+#     table['Name'] # => ["foo", "bat", "bad"]
+#     # Set a column, then get it.
+#     table['Name'] = ['Foo', 'Bar', 'Baz']
+#     table['Name'] # => ["Foo", "Bar", "Baz"]
 #
 class CSV::Table[out Elem] < Object
   include Enumerable[untyped]
@@ -2787,20 +3007,61 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - new(array_of_rows, headers: nil)
+  #   - CSV::Table.new(array_of_rows, headers = nil) -> csv_table
   # -->
-  # 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.
+  # Returns a new CSV::Table object.
   #
-  # The optional `headers` parameter can be set to Array of headers. If headers
-  # aren't set, headers are fetched from CSV::Row objects. Otherwise, headers()
-  # method will return headers being set in headers argument.
+  # *   Argument `array_of_rows` must be an Array of CSV::Row objects.
+  # *   Argument `headers`, if given, may be an Array of Strings.
   #
-  # A CSV::Table object supports the following Array methods through delegation:
   #
-  # *   empty?()
-  # *   length()
-  # *   size()
+  # ---
+  #
+  # Create an empty CSV::Table object:
+  #     table = CSV::Table.new([])
+  #     table # => #<CSV::Table mode:col_or_row row_count:1>
+  #
+  # Create a non-empty CSV::Table object:
+  #     rows = [
+  #       CSV::Row.new([], []),
+  #       CSV::Row.new([], []),
+  #       CSV::Row.new([], []),
+  #     ]
+  #     table  = CSV::Table.new(rows)
+  #     table # => #<CSV::Table mode:col_or_row row_count:4>
+  #
+  # ---
+  #
+  # If argument `headers` is an Array of Strings, those Strings become the table's
+  # headers:
+  #     table = CSV::Table.new([], headers: ['Name', 'Age'])
+  #     table.headers # => ["Name", "Age"]
+  #
+  # If argument `headers` is not given and the table has rows, the headers are
+  # taken from the first row:
+  #     rows = [
+  #       CSV::Row.new(['Foo', 'Bar'], []),
+  #       CSV::Row.new(['foo', 'bar'], []),
+  #       CSV::Row.new(['FOO', 'BAR'], []),
+  #     ]
+  #     table  = CSV::Table.new(rows)
+  #     table.headers # => ["Foo", "Bar"]
+  #
+  # If argument `headers` is not given and the table is empty (has no rows), the
+  # headers are also empty:
+  #     table  = CSV::Table.new([])
+  #     table.headers # => []
+  #
+  # ---
+  #
+  # Raises an exception if argument `array_of_rows` is not an Array object:
+  #     # Raises NoMethodError (undefined method `first' for :foo:Symbol):
+  #     CSV::Table.new(:foo)
+  #
+  # Raises an exception if an element of `array_of_rows` is not a CSV::Table
+  # object:
+  #     # Raises NoMethodError (undefined method `headers' for :foo:Symbol):
+  #     CSV::Table.new([:foo])
   #
   def initialize: (untyped array_of_rows, ?headers: untyped) -> untyped
 
@@ -2823,7 +3084,7 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - ==(other)
+  #   - table == other_table -> true or false
   # -->
   # Returns `true` if all each row of `self` `==` the corresponding row of
   # `other_table`, otherwise, `false`.
@@ -2848,17 +3109,23 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - table[n] -> row
-  #   - table[range] -> array_of_rows
-  #   - table[header] -> array_of_fields
+  #   - table[n] -> row or column_data
+  #   - table[range] -> array_of_rows or array_of_column_data
+  #   - table[header] -> array_of_column_data
   # -->
   # 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`:
+  #
+  # Fetch a Row by Its Integer Index
+  # :
+  # *   Form: `table[n]`, `n` an integer.
+  # *   Access mode: `:row` or `:col_or_row`.
+  # *   Return value: *nth* row of the table, if that row exists; otherwise `nil`.
+  #
+  #
+  # Returns the *nth* row of the table if that row exists:
   #     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>
@@ -2871,21 +3138,50 @@ class CSV::Table[out Elem] < Object
   #
   # Returns `nil` if `n` is too large or too small:
   #     table[4] # => nil
-  #     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).
+  # Raises an exception if the access mode is `:row` and `n` is not an Integer:
   #     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`:
+  #
+  # Fetch a Column by Its Integer Index
+  # :
+  # *   Form: `table[n]`, `n` an Integer.
+  # *   Access mode: `:col`.
+  # *   Return value: *nth* column of the table, if that column exists; otherwise
+  #     an Array of `nil` fields of length `self.size`.
+  #
+  #
+  # Returns the *nth* column of the table if that column exists:
+  #     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[1] # => ["0", "1", "2"]
+  #
+  # Counts backward from the last column if `n` is negative:
+  #     table[-2] # => ["foo", "bar", "baz"]
+  #
+  # Returns an Array of `nil` fields if `n` is too large or too small:
+  #     table[4] # => [nil, nil, nil]
+  #     table[-4] # => [nil, nil, nil]
+  #
+  # ---
+  #
+  #
+  # Fetch Rows by Range
+  # :
+  # *   Form: `table[range]`, `range` a Range object.
+  # *   Access mode: `:row` or `:col_or_row`.
+  # *   Return value: rows from the table, beginning at row `range.start`, if
+  #     those rows exists.
+  #
+  #
+  # Returns rows from the table, beginning at row `range.first`, if those rows
+  # exist:
   #     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>
@@ -2895,11 +3191,11 @@ class CSV::Table[out Elem] < Object
   #     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:
+  # If there are too few rows, returns all from `range.start` 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:
+  # 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:
@@ -2915,9 +3211,47 @@ class CSV::Table[out Elem] < Object
   #
   # ---
   #
-  # 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`:
+  #
+  # Fetch Columns by Range
+  # :
+  # *   Form: `table[range]`, `range` a Range object.
+  # *   Access mode: `:col`.
+  # *   Return value: column data from the table, beginning at column
+  #     `range.start`, if those columns exist.
+  #
+  #
+  # Returns column values from the table, if the column exists; the values are
+  # arranged by row:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.by_col!
+  #     table[0..1] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+  #
+  # Special case: if `range.start == headers.size`, returns an Array (size:
+  # `table.size`) of empty Arrays:
+  #     table[table.headers.size..50] # => [[], [], []]
+  #
+  # If `range.end` is negative, calculates the ending index from the end:
+  #     table[0..-1] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+  #
+  # If `range.start` is negative, calculates the starting index from the end:
+  #     table[-2..2] # => [["foo", "0"], ["bar", "1"], ["baz", "2"]]
+  #
+  # If `range.start` is larger than `table.size`, returns an Array of `nil`
+  # values:
+  #     table[4..4] # => [nil, nil, nil]
+  #
+  # ---
+  #
+  #
+  # Fetch a Column by Its String Header
+  # :
+  # *   Form: `table[header]`, `header` a String header.
+  # *   Access mode: `:col` or `:col_or_row`
+  # *   Return value: column data from the table, if that `header` exists.
+  #
+  #
+  # Returns column values from the table, if the column exists:
   #     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>
@@ -2938,96 +3272,248 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - []=(index_or_header, value)
+  #   - table[n] = row -> row
+  #   - table[n] = field_or_array_of_fields -> field_or_array_of_fields
+  #   - table[header] = field_or_array_of_fields -> field_or_array_of_fields
   # -->
-  # 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!().
+  # Puts data onto the table.
+  #
+  # ---
+  #
+  #
+  # Set a Row by Its Integer Index
+  # :
+  # *   Form: `table[n] = row`, `n` an Integer, `row` a CSV::Row instance or an
+  #     Array of fields.
+  # *   Access mode: `:row` or `:col_or_row`.
+  # *   Return value: `row`.
   #
-  # Rows may be set to an Array of values (which will inherit the table's
-  # headers()) or a CSV::Row.
   #
-  # Columns may be set to a single value, which is copied to each row of the
-  # column, or an Array of values. Arrays of values are assigned to rows top to
-  # bottom in row major order. Excess values are ignored and if the Array does not
-  # have a value for each row the extra rows will receive a `nil`.
+  # If the row exists, it is replaced:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     new_row = CSV::Row.new(['Name', 'Value'], ['bat', 3])
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     return_value = table[0] = new_row
+  #     return_value.equal?(new_row) # => true # Returned the row
+  #     table[0].to_h # => {"Name"=>"bat", "Value"=>3}
   #
-  # Assigning to an existing column or row clobbers the data. Assigning to new
-  # columns creates them at the right end of the table.
+  # With access mode `:col_or_row`:
+  #     table.by_col_or_row! # => #<CSV::Table mode:col_or_row row_count:4>
+  #     table[0] = CSV::Row.new(['Name', 'Value'], ['bam', 4])
+  #     table[0].to_h # => {"Name"=>"bam", "Value"=>4}
+  #
+  # With an Array instead of a CSV::Row, inherits headers from the table:
+  #     array = ['bad', 5]
+  #     return_value = table[0] = array
+  #     return_value.equal?(array) # => true # Returned the array
+  #     table[0].to_h # => {"Name"=>"bad", "Value"=>5}
+  #
+  # If the row does not exist, extends the table by adding rows: assigns rows with
+  # `nil` as needed:
+  #     table.size # => 3
+  #     table[5] = ['bag', 6]
+  #     table.size # => 6
+  #     table[3] # => nil
+  #     table[4]# => nil
+  #     table[5].to_h # => {"Name"=>"bag", "Value"=>6}
+  #
+  # Note that the `nil` rows are actually `nil`, not a row of `nil` fields.
+  #
+  # ---
+  #
+  #
+  # Set a Column by Its Integer Index
+  # :
+  # *   Form: `table[n] = array_of_fields`, `n` an Integer, `array_of_fields` an
+  #     Array of String fields.
+  # *   Access mode: `:col`.
+  # *   Return value: `array_of_fields`.
+  #
+  #
+  # If the column exists, it is replaced:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     new_col = [3, 4, 5]
+  #     table.by_col! # => #<CSV::Table mode:col row_count:4>
+  #     return_value = table[1] = new_col
+  #     return_value.equal?(new_col) # => true # Returned the column
+  #     table[1] # => [3, 4, 5]
+  #     # The rows, as revised:
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     table[0].to_h # => {"Name"=>"foo", "Value"=>3}
+  #     table[1].to_h # => {"Name"=>"bar", "Value"=>4}
+  #     table[2].to_h # => {"Name"=>"baz", "Value"=>5}
+  #     table.by_col! # => #<CSV::Table mode:col row_count:4>
+  #
+  # If there are too few values, fills with `nil` values:
+  #     table[1] = [0]
+  #     table[1] # => [0, nil, nil]
+  #
+  # If there are too many values, ignores the extra values:
+  #     table[1] = [0, 1, 2, 3, 4]
+  #     table[1] # => [0, 1, 2]
+  #
+  # If a single value is given, replaces all fields in the column with that value:
+  #     table[1] = 'bat'
+  #     table[1] # => ["bat", "bat", "bat"]
+  #
+  # ---
+  #
+  #
+  # Set a Column by Its String Header
+  # :
+  # *   Form: `table[header] = field_or_array_of_fields`, `header` a String
+  #     header, `field_or_array_of_fields` a field value or an Array of String
+  #     fields.
+  # *   Access mode: `:col` or `:col_or_row`.
+  # *   Return value: `field_or_array_of_fields`.
+  #
+  #
+  # If the column exists, it is replaced:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     new_col = [3, 4, 5]
+  #     table.by_col! # => #<CSV::Table mode:col row_count:4>
+  #     return_value = table['Value'] = new_col
+  #     return_value.equal?(new_col) # => true # Returned the column
+  #     table['Value'] # => [3, 4, 5]
+  #     # The rows, as revised:
+  #     table.by_row! # => #<CSV::Table mode:row row_count:4>
+  #     table[0].to_h # => {"Name"=>"foo", "Value"=>3}
+  #     table[1].to_h # => {"Name"=>"bar", "Value"=>4}
+  #     table[2].to_h # => {"Name"=>"baz", "Value"=>5}
+  #     table.by_col! # => #<CSV::Table mode:col row_count:4>
+  #
+  # If there are too few values, fills with `nil` values:
+  #     table['Value'] = [0]
+  #     table['Value'] # => [0, nil, nil]
+  #
+  # If there are too many values, ignores the extra values:
+  #     table['Value'] = [0, 1, 2, 3, 4]
+  #     table['Value'] # => [0, 1, 2]
+  #
+  # If the column does not exist, extends the table by adding columns:
+  #     table['Note'] = ['x', 'y', 'z']
+  #     table['Note'] # => ["x", "y", "z"]
+  #     # The rows, as revised:
+  #     table.by_row!
+  #     table[0].to_h # => {"Name"=>"foo", "Value"=>0, "Note"=>"x"}
+  #     table[1].to_h # => {"Name"=>"bar", "Value"=>1, "Note"=>"y"}
+  #     table[2].to_h # => {"Name"=>"baz", "Value"=>2, "Note"=>"z"}
+  #     table.by_col!
+  #
+  # If a single value is given, replaces all fields in the column with that value:
+  #     table['Value'] = 'bat'
+  #     table['Value'] # => ["bat", "bat", "bat"]
   #
   def []=: (untyped index_or_header, untyped value) -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - by_col()
+  #   - table.by_col -> table_dup
   # -->
-  # 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.
+  # Returns a duplicate of `self`, in column mode (see [Column
+  # Mode](#class-CSV::Table-label-Column+Mode)):
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.mode # => :col_or_row
+  #     dup_table = table.by_col
+  #     dup_table.mode # => :col
+  #     dup_table.equal?(table) # => false # It's a dup
+  #
+  # This may be used to chain method calls without changing the mode (but also
+  # will affect performance and memory usage):
+  #     dup_table.by_col['Name']
   #
-  # This method returns the duplicate table for chaining. Don't chain destructive
-  # methods (like []=()) this way though, since you are working with a duplicate.
+  # Also note that changes to the duplicate table will not affect the original.
   #
   def by_col: () -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - by_col!()
+  #   - table.by_col! -> self
   # -->
-  # 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.
-  #
-  # This method returns the table and is safe to chain.
+  # Sets the mode for `self` to column mode (see [Column
+  # Mode](#class-CSV::Table-label-Column+Mode)); returns `self`:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.mode # => :col_or_row
+  #     table1 = table.by_col!
+  #     table.mode # => :col
+  #     table1.equal?(table) # => true # Returned self
   #
   def by_col!: () -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - by_col_or_row()
+  #   - table.by_col_or_row -> table_dup
   # -->
-  # 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.
+  # Returns a duplicate of `self`, in mixed mode (see [Mixed
+  # Mode](#class-CSV::Table-label-Mixed+Mode)):
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true).by_col!
+  #     table.mode # => :col
+  #     dup_table = table.by_col_or_row
+  #     dup_table.mode # => :col_or_row
+  #     dup_table.equal?(table) # => false # It's a dup
   #
-  # This method returns the duplicate table for chaining.  Don't chain destructive
-  # methods (like []=()) this way though, since you are working with a duplicate.
+  # This may be used to chain method calls without changing the mode (but also
+  # will affect performance and memory usage):
+  #     dup_table.by_col_or_row['Name']
+  #
+  # Also note that changes to the duplicate table will not affect the original.
   #
   def by_col_or_row: () -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - by_col_or_row!()
+  #   - table.by_col_or_row! -> self
   # -->
-  # 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
-  # while anything else is assumed to be column access by headers.
-  #
-  # This method returns the table and is safe to chain.
+  # Sets the mode for `self` to mixed mode (see [Mixed
+  # Mode](#class-CSV::Table-label-Mixed+Mode)); returns `self`:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true).by_col!
+  #     table.mode # => :col
+  #     table1 = table.by_col_or_row!
+  #     table.mode # => :col_or_row
+  #     table1.equal?(table) # => true # Returned self
   #
   def by_col_or_row!: () -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - by_row()
+  #   - table.by_row -> table_dup
   # -->
-  # 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.
+  # Returns a duplicate of `self`, in row mode (see [Row
+  # Mode](#class-CSV::Table-label-Row+Mode)):
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.mode # => :col_or_row
+  #     dup_table = table.by_row
+  #     dup_table.mode # => :row
+  #     dup_table.equal?(table) # => false # It's a dup
+  #
+  # This may be used to chain method calls without changing the mode (but also
+  # will affect performance and memory usage):
+  #     dup_table.by_row[1]
   #
-  # This method returns the duplicate table for chaining.  Don't chain destructive
-  # methods (like []=()) this way though, since you are working with a duplicate.
+  # Also note that changes to the duplicate table will not affect the original.
   #
   def by_row: () -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - by_row!()
+  #   - table.by_row! -> self
   # -->
-  # 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.
-  #
-  # This method returns the table and is safe to chain.
+  # Sets the mode for `self` to row mode (see [Row
+  # Mode](#class-CSV::Table-label-Row+Mode)); returns `self`:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.mode # => :col_or_row
+  #     table1 = table.by_row!
+  #     table.mode # => :row
+  #     table1.equal?(table) # => true # Returned self
   #
   def by_row!: () -> untyped
 
@@ -3076,7 +3562,7 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - delete_if() { |header, self| ... }
+  #   - table.delete_if {|row_or_column| ... } -> self
   # -->
   # Removes rows or columns for which the block returns a truthy value; returns
   # `self`.
@@ -3119,7 +3605,7 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - each() { |header, self| ... }
+  #   - table.each {|row_or_column| ... ) -> self
   # -->
   # Calls the block with each row or column; returns `self`.
   #
@@ -3155,19 +3641,43 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - headers()
+  #   - table.headers -> array_of_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.
+  # Returns a new Array containing the String headers for the table.
+  #
+  # If the table is not empty, returns the headers from the first row:
+  #     rows = [
+  #       CSV::Row.new(['Foo', 'Bar'], []),
+  #       CSV::Row.new(['FOO', 'BAR'], []),
+  #       CSV::Row.new(['foo', 'bar'], []),
+  #     ]
+  #     table  = CSV::Table.new(rows)
+  #     table.headers # => ["Foo", "Bar"]
+  #     table.delete(0)
+  #     table.headers # => ["FOO", "BAR"]
+  #     table.delete(0)
+  #     table.headers # => ["foo", "bar"]
+  #
+  # If the table is empty, returns a copy of the headers in the table itself:
+  #     table.delete(0)
+  #     table.headers # => ["Foo", "Bar"]
   #
   def headers: () -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - inspect()
+  #   - table.inspect => string
   # -->
-  # Shows the mode and size of this table in a US-ASCII String.
+  # Returns a `US-ASCII`-encoded String showing table:
+  # *   Class: `CSV::Table`.
+  # *   Access mode: `:row`, `:col`, or `:col_or_row`.
+  # *   Size:  Row count, including the header row.
+  #
+  #
+  # Example:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.inspect # => "#<CSV::Table mode:col_or_row row_count:4>\nName,Value\nfoo,0\nbar,1\nbaz,2\n"
   #
   def inspect: () -> String
 
@@ -3201,28 +3711,39 @@ class CSV::Table[out Elem] < Object
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - to_a()
+  #   - table.to_a -> array_of_arrays
   # -->
-  # Returns the table as an Array of Arrays. Headers will be the first row, then
-  # all of the field rows will follow.
+  # Returns the table as an Array of Arrays; the headers are in the first row:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.to_a # => [["Name", "Value"], ["foo", "0"], ["bar", "1"], ["baz", "2"]]
   #
   def to_a: () -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - to_csv(write_headers: true, **options)
+  #   - table.to_csv(**options) -> csv_string
   # -->
-  # Returns the table as a complete CSV String. Headers will be listed first, then
-  # all of the field rows.
+  # Returns the table as CSV string. See [Options for
+  # Generating](../CSV.html#class-CSV-label-Options+for+Generating).
+  #
+  # Defaults option `write_headers` to `true`:
+  #     source = "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #     table = CSV.parse(source, headers: true)
+  #     table.to_csv # => "Name,Value\nfoo,0\nbar,1\nbaz,2\n"
+  #
+  # Omits the headers if option `write_headers` is given as `false` (see {Option
+  # `write_headers`[}](../CSV.html#class-CSV-label-Option+write_headers)):
+  #     table.to_csv(write_headers: false) # => "foo,0\nbar,1\nbaz,2\n"
   #
-  # This method assumes you want the Table.headers(), unless you explicitly pass
-  # `:write_headers => false`.
+  # Limit rows if option `limit` is given like `2`:
+  #     table.to_csv(limit: 2) # => "Name,Value\nfoo,0\nbar,1\n"
   #
   def to_csv: (?write_headers: boolish, **untyped) -> untyped
 
   # <!--
   #   rdoc-file=lib/csv/table.rb
-  #   - to_s(write_headers: true, **options)
+  #   - to_s(write_headers: true, limit: nil, **options)
   # -->
   #
   alias to_s to_csv