[DOC] Enhanced RDoc for io.c #5451
Conversation
io.c
Outdated
| @@ -8159,13 +8171,12 @@ rb_io_printf(int argc, const VALUE *argv, VALUE out) | |||
|
|
|||
| /* | |||
| * call-seq: | |||
| * printf(io, string [, obj ... ]) -> nil | |||
| * printf(string [, obj ... ]) -> nil | |||
| * printf(string, *objects) -> nil | |||
There was a problem hiding this comment.
The case where the first argument is a string is treated differently than the case where the first argument is not a string. Additionally, the method supports being passed no arguments (doing nothing in that case), So there should be three lines in call-seq, and you should probably have two examples, one for io provided, and one for io not provided (no example needed for no arguments).
There was a problem hiding this comment.
Have not succeeded in forming an example for printf(io, string [, obj ... ]) . Need help.
There was a problem hiding this comment.
printf($stderr, "%d", 1)
There was a problem hiding this comment.
Updated. Can I get by with a 2-line call-seq?
|
@zverok Since you are interested in improving Ruby's documentation, maybe you can take over reviewing @BurdetteLamar's documentation changes going forward? However, if not, I'm fine continuing to do so. |
io.c
Outdated
| @@ -8159,13 +8171,33 @@ rb_io_printf(int argc, const VALUE *argv, VALUE out) | |||
|
|
|||
| /* | |||
| * call-seq: | |||
| * printf(io, string [, obj ... ]) -> nil | |||
| * printf(string [, obj ... ]) -> nil | |||
| * printf(io = $stdout, string, *objects) -> nil | |||
There was a problem hiding this comment.
You need a separate call-seq line for the io case. the call-seq you are using is not valid Ruby syntax (cannot have a required parameter between an optional parameter and a splat).
Don't see @zverok on the reviewers dropdown. |
|
I'll definitely take a look later today 👍
My credentials receiving is in progress yet 😀 |
|
@zverok, thanks! Looking forward to our working together. |
|
@jeremyevans, is this ready to merge? |
|
@BurdetteLamar Can you wait till I have a look (today at the evening)? |
Sure thing. Just wondering, what timezone are you in? |
|
GMT+2. I typically have my OSS time after 8pm my timezone (e.g. 6pm UTC) |
io.c
Outdated
| * ios.set_encoding_by_bom -> encoding or nil | ||
| * set_encoding_by_bom -> encoding or nil | ||
| * | ||
| * If the stream begins with a BOM, consumes the BOM |
There was a problem hiding this comment.
I think we shoud explain what's BOM here, it is not a common knowledge and not exactly easy to Google :)
There was a problem hiding this comment.
Added link to wikipedia BOM.
|
@zverok, if ok with your, I'd like to do these mods and re-reviews piecemeal, while If get the feel of some new strategies. |
io.c
Outdated
| * Writes the given object(s) to <em>ios</em>. Returns +nil+. | ||
| * Writes the given objects to the stream; returns +nil+. | ||
| * Appends the output record separator <tt>$OUTPUT_RECORD_SEPARATOR</tt> | ||
| * <tt>$\\</tt>), if it is not +nil+. |
There was a problem hiding this comment.
| * <tt>$\\</tt>), if it is not +nil+. | |
| * (<tt>$\\</tt>), if it is not +nil+. |
io.c
Outdated
| * - Converts via its method +to_s+ if not a string. | ||
| * - Writes to the stream. | ||
| * - If not the last object, writes the output field separator | ||
| * <tt>$OUTPUT_FIELD_SEPARATOR</tt> (<tt>$,</tt> if it is not +nil+. |
There was a problem hiding this comment.
| * <tt>$OUTPUT_FIELD_SEPARATOR</tt> (<tt>$,</tt> if it is not +nil+. | |
| * <tt>$OUTPUT_FIELD_SEPARATOR</tt> (<tt>$,</tt>) if it is not +nil+. |
io.c
Outdated
| * set_encoding_by_bom -> encoding or nil | ||
| * | ||
| * If the stream begins with a BOM | ||
| * ({byte order marker}[https://en.wikipedia.org/wiki/Byte_order_mark], |
There was a problem hiding this comment.
| * ({byte order marker}[https://en.wikipedia.org/wiki/Byte_order_mark], | |
| * ({byte order marker}[https://en.wikipedia.org/wiki/Byte_order_mark]), |
Treats: