2 files changed, 45 insertions, 32 deletions
diff --git a/doc/csv/options/parsing/converters.rdoc b/doc/csv/options/parsing/converters.rdoc
index 993803c5d0..211fa48de6 100644
--- a/doc/csv/options/parsing/converters.rdoc
+++ b/doc/csv/options/parsing/converters.rdoc
@@ -1,41 +1,42 @@
 ====== Option +converters+
 
-Specifies a single field converter name or \Proc,
-or an \Array of field converter names and Procs.
-
+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 single field converter name:
+The value may be a field converter name
+(see {Stored Converters}[#class-CSV-label-Stored+Converters]):
   str = '1,2,3'
   # Without a converter
-  ary = CSV.parse_line(str)
-  ary # => ["1", "2", "3"]
+  array = CSV.parse_line(str)
+  array # => ["1", "2", "3"]
   # With built-in converter :integer
-  ary = CSV.parse_line(str, converters: :integer)
-  ary # => [1, 2, 3]
+  array = CSV.parse_line(str, converters: :integer)
+  array # => [1, 2, 3]
 
-The value may be an \Array of field converter names:
+The value may be a converter list
+(see {Converter Lists}[#class-CSV-label-Converter+Lists]):
   str = '1,3.14159'
   # Without converters
-  ary = CSV.parse_line(str)
-  ary # => ["1", "3.14159"]
+  array = CSV.parse_line(str)
+  array # => ["1", "3.14159"]
   # With built-in converters
-  ary = CSV.parse_line(str, converters: [:integer, :float])
-  ary # => [1, 3.14159]
+  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
-  ary = CSV.parse_line(str)
-  ary # => [" foo  ", "  bar  ", "  baz  "]
+  array = CSV.parse_line(str)
+  array # => [" foo  ", "  bar  ", "  baz  "]
   # With a custom converter
-  ary = CSV.parse_line(str, converters: proc {|field| field.strip })
-  ary # => ["foo", "bar", "baz"]
+  array = CSV.parse_line(str, converters: proc {|field| field.strip })
+  array # => ["foo", "bar", "baz"]
 
-See also {Custom Converters}[#class-CSV-label-Custom+Converters]
+See also {Custom Field Converters}[#class-CSV-label-Custom+Field+Converters]
 
 ---
 
diff --git a/doc/csv/options/parsing/header_converters.rdoc b/doc/csv/options/parsing/header_converters.rdoc
index 329d96a897..309180805f 100644
--- a/doc/csv/options/parsing/header_converters.rdoc
+++ b/doc/csv/options/parsing/header_converters.rdoc
@@ -1,6 +1,7 @@
 ====== Option +header_converters+
 
-Specifies a \String converter name or an \Array of converter names.
+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
@@ -10,22 +11,33 @@ except that:
 - The converters apply only to the header row.
 - The built-in header converters are +:downcase+ and +:symbol+.
 
-Examples:
+This section assumes prior execution of:
   str = <<-EOT
+  Name,Value
   foo,0
   bar,1
   baz,2
   EOT
-  headers = ['Name', 'Value']
   # With no header converter
-  csv = CSV.parse(str, headers: headers)
-  csv.headers # => ["Name", "Value"]
-  # With header converter :downcase
-  csv = CSV.parse(str, headers: headers, header_converters: :downcase)
-  csv.headers # => ["name", "value"]
-  # With header converter :symbol
-  csv = CSV.parse(str, headers: headers, header_converters: :symbol)
-  csv.headers # => [:name, :value]
-  # With both
-  csv = CSV.parse(str, headers: headers, header_converters: [:downcase, :symbol])
-  csv.headers # => [:name, :value]
+  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]
+