[ruby/csv] doc: fix return value of open {} and use File.open {} (#139)

* Enhanced RDoc for CSV

* Repair example code for foreach
https://github.com/ruby/csv/commit/16b425eb37

1 files changed, 8 insertions, 4 deletions

diff --git a/lib/csv.rb b/lib/csv.rb
index 65f31a6fa8..35921db37b 100644
--- a/lib/csv.rb
+++ b/lib/csv.rb
@@ -863,7 +863,10 @@ class CSV
     #   ["baz", "2"]
     #
     # Read rows from an \IO object:
-    #   CSV.foreach(File.open(path)) {|row| p row } # => 21
+    #   File.open(path) do |file|
+    #     CSV.foreach(file) {|row| p row } # => 21
+    #   end
+    #
     # Output:
     #   ["foo", "0"]
     #   ["bar", "1"]
@@ -1023,8 +1026,8 @@ class CSV
     # :call-seq:
     #   open(file_path, mode = "rb", **options ) -> new_csv
     #   open(io, mode = "rb", **options ) -> new_csv
-    #   open(file_path, mode = "rb", **options ) { |csv| ... } -> new_csv
-    #   open(io, mode = "rb", **options ) { |csv| ... } -> new_csv
+    #   open(file_path, mode = "rb", **options ) { |csv| ... } -> object
+    #   open(io, mode = "rb", **options ) { |csv| ... } -> object
     #
     # possible options elements:
     #   hash form:
@@ -1071,7 +1074,8 @@ class CSV
     #
     # ---
     #
-    # With a block given, calls the block with the created \CSV object:
+    # With a block given, calls the block with the created \CSV object;
+    # returns the block's return value:
     #
     # Using a file path:
     #   csv = CSV.open(path) {|csv| p csv}