Bug #13306
closed[DOC] rdoc for IO#puts
Description
This would effectively revert your recent r57944, so please give ok for me to apply this patch.
I don't think the mention of IO#write (or IO#print) is necessary (implementation detail); instead I expanded the docs with some information copied from write/print, like e.g. mention of to_s
.
And I do not understand at all how puts should have an effect on the input record separator, or why someone would assume it might have.
diff --git a/io.c b/io.c
index f1cdc56..e727d0a 100644
--- a/io.c
+++ b/io.c
@@ -7181,15 +7181,17 @@ io_puts_ary(VALUE ary, VALUE out, int recur)
* call-seq:
* ios.puts(obj, ...) -> nil
*
- * Writes the given object(s) to <em>ios</em> as with <code>IO#write</code>.
+ * Writes the given object(s) to <em>ios</em>.
* Writes a newline after any that do not already end
- * with a newline sequence.
+ * with a newline sequence. Returns +nil+.
*
+ * The stream must be opened for writing.
* If called with an array argument, writes each element on a new line.
+ * Each given object that isn't a string or array will be converted
+ * by calling its <code>to_s</code> method.
* If called without arguments, outputs a single newline.
- * This doesn't affect $/. ($RS or INPUT_RECORD_SEPARATOR in English.rb)
*
- * $stdout.puts("this", "is", "a", "test")
+ * $stdout.puts("this", "is", ["a", "test"])
*
* <em>produces:</em>
*
--
1.9.1
Updated by stomar (Marcus Stollsteimer) about 7 years ago
I very much think the output record separator was meant, and I suggest the following:
diff --git a/io.c b/io.c
index cd615fb..fabd5d5 100644
--- a/io.c
+++ b/io.c
@@ -7185,15 +7185,17 @@ io_puts_ary(VALUE ary, VALUE out, int recur)
* call-seq:
* ios.puts(obj, ...) -> nil
*
- * Writes the given object(s) to <em>ios</em> as with <code>IO#write</code>.
+ * Writes the given object(s) to <em>ios</em>.
* Writes a newline after any that do not already end
- * with a newline sequence.
+ * with a newline sequence. Returns +nil+.
*
+ * The stream must be opened for writing.
* If called with an array argument, writes each element on a new line.
+ * Each given object that isn't a string or array will be converted
+ * by calling its <code>to_s</code> method.
* If called without arguments, outputs a single newline.
- * This doesn't affect $/. ($RS or $INPUT_RECORD_SEPARATOR in English.rb)
*
- * $stdout.puts("this", "is", "a", "test")
+ * $stdout.puts("this", "is", ["a", "test"])
*
* <em>produces:</em>
*
@@ -7201,6 +7203,9 @@ io_puts_ary(VALUE ary, VALUE out, int recur)
* is
* a
* test
+ *
+ * Note that +puts+ always uses newlines and is not affected
+ * by the output record separator (<code>$\\</code>).
*/
VALUE
--
1.9.1
Since the record separator is of no use here, IMO it doesn't make sense to mention "English"; furthermore, the other methods of IO also only mention the "non-English" forms.
I'll apply in a couple of days unless there are objections.
Updated by stomar (Marcus Stollsteimer) about 7 years ago
- Assignee changed from naruse (Yui NARUSE) to stomar (Marcus Stollsteimer)
- ruby -v changed from head to r58059
Updated by stomar (Marcus Stollsteimer) about 7 years ago
- Status changed from Open to Closed
Updated by usa (Usaku NAKAMURA) about 7 years ago
- Backport changed from 2.2: UNKNOWN, 2.3: UNKNOWN, 2.4: UNKNOWN to 2.2: REQUIRED, 2.3: REQUIRED, 2.4: REQUIRED
Updated by usa (Usaku NAKAMURA) almost 7 years ago
- Backport changed from 2.2: REQUIRED, 2.3: REQUIRED, 2.4: REQUIRED to 2.2: REQUIRED, 2.3: DONE, 2.4: REQUIRED
ruby_2_3 r58517 merged revision(s) 58062.
Updated by nagachika (Tomoyuki Chikanaga) over 6 years ago
- Backport changed from 2.2: REQUIRED, 2.3: DONE, 2.4: REQUIRED to 2.2: REQUIRED, 2.3: DONE, 2.4: DONE
ruby_2_4 r59808 merged revision(s) 57944,57977,58062.