Project

General

Profile

Bug #13306

[DOC] rdoc for IO#puts

Added by stomar (Marcus Stollsteimer) about 2 years ago. Updated over 1 year ago.

Status:
Closed
Priority:
Normal
Target version:
-
[ruby-core:80081]

Description

naruse (Yui NARUSE)

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

Associated revisions

Revision 5f5f648c
Added by stomar (Marcus Stollsteimer) about 2 years ago

io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@58062 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 58062
Added by stomar (Marcus Stollsteimer) about 2 years ago

io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

Revision 58062
Added by stomar (Marcus Stollsteimer) about 2 years ago

io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

Revision 58062
Added by stomar (Marcus Stollsteimer) about 2 years ago

io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

Revision 410c048a
Added by usa (Usaku NAKAMURA) almost 2 years ago

merge revision(s) 58062: [Backport #13306]

io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_3@58517 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 58517
Added by usa (Usaku NAKAMURA) almost 2 years ago

merge revision(s) 58062: [Backport #13306]

io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

Revision 428687e9
Added by nagachika (Tomoyuki Chikanaga) over 1 year ago

merge revision(s) 57944,57977,58062: [Backport #13306]

io.c: [DOC] IO#puts uses IO#write
io.c: [DOC] add missing `$`
io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_4@59808 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

Revision 59808
Added by nagachika (Tomoyuki Chikanaga) over 1 year ago

merge revision(s) 57944,57977,58062: [Backport #13306]

io.c: [DOC] IO#puts uses IO#write
io.c: [DOC] add missing `$`
io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

History

Updated by stomar (Marcus Stollsteimer) about 2 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 2 years ago

  • ruby -v changed from head to r58059
  • Assignee changed from naruse (Yui NARUSE) to stomar (Marcus Stollsteimer)
#3

Updated by stomar (Marcus Stollsteimer) about 2 years ago

  • Status changed from Open to Closed

Applied in changeset r58062.


io.c: [DOC] expand docs for IO#puts

[ruby-core:80081] [Bug #13306]

#4

Updated by usa (Usaku NAKAMURA) about 2 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 2 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 1 year 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.

Also available in: Atom PDF