1 files changed, 26 insertions, 14 deletions
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]
+