[DOC] Enhanced RDoc for IO #6669

BurdetteLamar · 2022-11-03T18:34:20Z

This resolves discrepancies between io.c and doc/io_streams.rdoc. By previous agreement, examples for methods belong in the former; the latter may have examples for certain values and concepts.

This also improves the doc for line number, which previously was unclear and incomplete.

peterzhu2118

While I think improving the docs for IO is very much needed, I'm not sure if I see the value for some of these sections in io_streams.rdoc. I personally find linking to different pages in documentation difficult to follow and less time-efficient to read. Here are some examples:

"Line Options": There's only a single keyword argument listed. IMO making the reader go to another page just to read a single sentence is counterintuitive and would save them so much time if it was just embedded in the docs for IO.
Most sections like "Basic IO", "End-of-Stream", "Line IO", "Line Separator", "Character IO", "Byte IO", "Codepoint IO", etc. are basically another way to group "What's Here" sections. Maybe it should belong in the docs of IO?

peterzhu2118 · 2022-11-03T20:44:31Z

doc/io_streams.rdoc

- IO#read: Returns all remaining or the next _n_ bytes read from the stream,
-  for a given _n_:
+- IO#read: Reads and returns some or all of the remaining bytes from the stream.
+- IO#write: Writes zero or more strings to the stream, derived from the given objects:


I'm not sure what "derived from the given objects" means. Could you clarify?

Modified (clarified?).

peterzhu2118 · 2022-11-03T20:46:28Z

doc/io_streams.rdoc

-    f.lineno   # => 0
-    f.close
+- IO#tell (aliased as +#pos+): Returns the current position (in bytes) in the stream.
+- IO#pos=: Sets the position of the stream to a given integer +new_position_ (in bytes):


Suggested change

- IO#pos=: Sets the position of the stream to a given integer +new_position_ (in bytes):

- IO#pos=: Sets the position of the stream to a given integer +new_position_ (in bytes).

peterzhu2118 · 2022-11-06T15:06:19Z

doc/io_streams.rdoc


  f = File.new('t.txt')
  f.eof? # => false
  f.read # => "First line\nSecond line\n\nFourth line\nFifth line\n"
  f.eof? # => true

-Or by using method IO#seek:


I prefer this old format that separates the two examples. I find longer examples to be hard to read. I also prefer if we showed IO#seek first since it avoids reading all the contents of the file (which can be slow if the file is very large).

peterzhu2118 · 2022-11-06T15:09:59Z

io.c

- *  Sets and returns the line number for the stream.
- *  See {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number].
+ *  Sets and returns the line number for the stream;
+ *  see {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number]:


Suggested change

* see {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number]:

* see {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number].

peterzhu2118 · 2022-11-06T15:10:45Z

io.c

 *  returns +self+.
+ *  does nothing if already at end-of-stream;


Suggested change

* does nothing if already at end-of-stream;

* Does nothing if already at end-of-stream;

peterzhu2118 · 2022-11-06T15:14:03Z

io.c

+ *    File.read('t.dat')
+ *    # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
+ *    File.read('t.dat')
+ *    # => "\xFE\xFF\x99\x90\x99\x91\x99\x92\x99\x93\x99\x94"
+ *    f = File.new('t.dat')
+ *    f.getbyte # => 254
+ *    f.getbyte # => 255
+ *    f.seek(-2, :END)
+ *    f.getbyte # => 153
+ *    f.getbyte # => 148
+ *    f.getbyte # => nil
+ *    f.close


What's the purpose of adding these examples? Adding this makes the examples very long, could we shorten it with the example above?

peterzhu2118 · 2022-11-06T15:25:42Z

doc/io_streams.rdoc

+    f.rewind
+    f.seek(0, :SET)
+    $.          # => 5
+    $.          # => 5


Why is $. outputted twice here?

One removed.

BurdetteLamar · 2022-11-06T20:23:18Z

* "Line Options": There's only a single keyword argument listed. IMO making the reader go to another page just to read a single sentence is counterintuitive and would save them so much time if it was just embedded in the docs for IO.

Section and links thereto removed.

BurdetteLamar · 2022-11-06T20:28:22Z

* Most sections like "Basic IO", "End-of-Stream", "Line IO", "Line Separator", "Character IO", "Byte IO", "Codepoint IO", etc. are basically another way to group "What's Here" sections. Maybe it should belong in the docs of `IO`?

I'd planned to link to these sections from ARGF, IO, StringIO, Kernel, and possibly File. I put them here b/c they cite methods common to (almost) all. I've considered linking from these sections to methods in all the classes (instead of saying what they're in and not in; thoughts?

peterzhu2118 · 2022-11-07T14:51:37Z

I think most readers would be reading for IO rather than any of the other classes, so if we could avoid linking out in IO`and instead link out to IO in the other classes, then we could at least improve the reading experience in IO. I also find the "(also in ABC)" and "(not in XYZ)" parts rather difficult to follow, if we linked to IO from these other classes, we could avoid doing this.

BurdetteLamar · 2022-11-07T16:09:38Z

I think most readers would be reading for IO rather than any of the other classes, so if we could avoid linking out in IO`and instead link out to IO in the other classes, then we could at least improve the reading experience in IO.

I don't envision readers repeatedly following individual links from class IO to page IO Streams. Instead, I envision them landing on page IO Streams a first or second time, then reading deeply there.

I think the discussion of IO streams of all kinds has value. There's no other place in the doc where the reader can get a sense of a family of methods such as those in sections "Position," "Open and Closed Steams," "Line IO," and "Character IO."

I also find the "(also in ABC)" and "(not in XYZ)" parts rather difficult to follow, if we linked to IO from these other classes, we could avoid doing this.

I've planned on adding this table, which would (trivially) require changing the page from .rdoc to .md. Note that the table cannot be added to io.c (it's not markdown):

| Method         | ARGF | IO/File | StringIO | Kernel |
|:---------------|------|---------|----------|--------|
| close          | x    | x       | x        |        |
| close_read     |      | x       | x        |        |
| close_write    |      | x       | x        |        |
| closed?        | x    | x       | x        |        |
| each           | x    | x       | x        |        |
| each_byte      | x    | x       | x        |        |
| each_char      | x    | x       | x        |        |
| each_codepoint | x    | x       | x        |        |
| each_line      | x    | x       | x        |        |
| eof            | x    | x       | x        |        |
| eof?           | x    | x       | x        |        |
| getbyte        | x    | x       | x        |        |
| getc           | x    | x       | x        |        |
| gets           | x    | x       | x        | x      |
| lineno         | x    | x       | x        |        |
| lineno=        | x    | x       | x        |        |
| pos            | x    | x       | x        |        |
| pos=           | x    | x       | x        |        |
| putc           | x    | x       | x        | x      |
| puts           | x    | x       |          | x      |
| read           | x    | x       | x        |        |
| read_nonblock  | x    | x       |          |        |
| readbyte       | x    | x       |          |        |
| readchar       | x    | x       |          |        |
| readline       | x    | x       |          | x      |
| readlines      | x    | x       | x        | x      |
| readpartial    | x    | x       |          |        |
| reopen         |      | x       | x        |        |
| rewind         | x    | x       | x        |        |
| seek           | x    | x       | x        |        |
| tell           | x    | x       | x        |        |
| ungetbyte      |      | x       | x        |        |
| ungetc         |      | x       | x        |        |
| write          | x    | x       | x        |        |

peterzhu2118 · 2022-11-07T17:05:39Z

For me, when I read documentation, I want it to be the source of truth with all of the information available. I usually have an idea of what I'm looking for so it's important to me that most (or all) of the information about the class is available on a single page so it's easy to read and search.

I think the discussion of IO streams of all kinds has value. There's no other place in the doc where the reader can get a sense of a family of methods such as those in sections "Position," "Open and Closed Steams," "Line IO," and "Character IO."

Again, this sounds like a "What's here" section that could live in the documentation for the respective classes. Discussion about specifically what "Line IO" or "Character IO" means could live in the documentation in IO and linked to from other classes (e.g. StringIO or ARGF). Another way would be to create small rdoc fragments and each of these classes could use an :include: directive to include them rather than linking.

Again, my main problem here is that this document includes a list of methods where most of it links to methods in IO and so it may or may not exist in the class they're looking at

I've planned on adding this table, which would (trivially) require changing the page from .rdoc to .md. Note that the table cannot be added to io.c (it's not markdown):

I'm not sure what the value of the table is. If I wanted to look at what methods are available for the class, there's a summary on the left hand side of the documentation of the class with the methods of that class.

BurdetteLamar · 2022-11-07T18:16:14Z

So why have the IO Stream page at all?

peterzhu2118 · 2022-11-07T18:57:02Z

I'm saying we could move many of the parts of this document into the documentation in IO and link to IO from the other classes. It should at least improve the experience of reading documentation in IO.

BurdetteLamar · 2022-11-07T20:07:22Z

I'm saying we could move many of the parts of this document into the documentation in IO and link to IO from the other classes. It should at least improve the experience of reading documentation in IO.

So what, if anything, should remain on the io_streams page?

peterzhu2118 · 2022-11-07T20:20:41Z

I think most of these can be moved to the docs for the IO class. But I can only give my opinion from how I use the docs, and you may have other opinions.

BurdetteLamar · 2022-11-07T20:49:33Z

I think most of these can be moved to the docs for the IO class. But I can only give my opinion from how I use the docs, and you may have other opinions.

I'll plan to merge io_stream.rdoc into io.c.

BurdetteLamar · 2022-11-08T19:49:28Z

@peterzhu2118, ready for you.

peterzhu2118

I really like this change, thank you for making the change!

I think there's links to io_streams.rdoc in file.c and stringio.c that should be updated to make sure there's no dead links.

io.c

BurdetteLamar · 2022-11-09T15:47:35Z

I really like this change, thank you for making the change!

I think there's links to io_streams.rdoc in file.c and stringio.c that should be updated to make sure there's no dead links.

Fixed in file.c here. stringio.c needs separate PR in separate repository; working on it.

BurdetteLamar · 2022-11-09T16:04:57Z

@peterzhu2118, I'm thinking to have free-standing doc for StringIO and ARGF -- i.e., not linking to IO. Their code is separate, and could conceivably behave differently.

peterzhu2118

Looks good, thanks for addressing the comments!

peterzhu2118 · 2022-11-09T16:06:25Z

Can you give some examples about how they behave differently? I would expect behaviour differences to be explained in their respective documentation.

BurdetteLamar · 2022-11-09T16:14:31Z

Can you give some examples about how they behave differently? I would expect behaviour differences to be explained in their respective documentation.

Not aware of any differences. But I'd like the docs to be free-standing anyway; I'm thinking of sections in class doc:

Basic IO
Position
Open and Closed Streams
End-of-Stream
Line IO
Character IO
Byte IO
Codepoint IO

For reasons you've given elsewhere (searchability, etc.), the link targets should be local. And the examples should show the local class in action, not link to examples using a different class.

peterzhu2118 · 2022-11-09T16:33:11Z

I think it makes more sense for most of the documentation to live in IO because although StringIO and ARGF isn't aren't IO, it's designed to look like IO as much as possible. And for that reason, I think readers should read documentation of IO to have a good understanding of how StringIO/ARGF works.

BurdetteLamar · 2022-11-09T16:55:30Z

I think it makes more sense for most of the documentation to live in IO because although StringIO and ARGF isn't aren't IO, it's designed to look like IO as much as possible. And for that reason, I think readers should read documentation of IO to have a good understanding of how StringIO/ARGF works.

I do not agree. I think readers should get a good understanding of how StringIO/ARGF works by reading about StringIO/ARGF.

Enhanced RDoc for IO

b8043e2

BurdetteLamar requested a review from peterzhu2118 November 3, 2022 18:34

BurdetteLamar added the Documentation Improvements to documentation. label Nov 3, 2022

peterzhu2118 reviewed Nov 6, 2022

View reviewed changes

BurdetteLamar added 2 commits November 6, 2022 20:16

Enhanced RDoc for IO

100c113

Enhanced RDoc for IO

bd3263a

BurdetteLamar requested a review from peterzhu2118 November 6, 2022 20:28

Enhanced RDoc for IO

6b57540

peterzhu2118 reviewed Nov 9, 2022

View reviewed changes

io.c Show resolved Hide resolved

io.c Outdated Show resolved Hide resolved

io.c Outdated Show resolved Hide resolved

io.c Show resolved Hide resolved

Enhanced RDoc for IO

09aacd4

peterzhu2118 approved these changes Nov 9, 2022

View reviewed changes

BurdetteLamar merged commit 0e1e1b1 into ruby:master Nov 9, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[DOC] Enhanced RDoc for IO #6669

[DOC] Enhanced RDoc for IO #6669

BurdetteLamar commented Nov 3, 2022

peterzhu2118 left a comment

peterzhu2118 Nov 3, 2022

BurdetteLamar Nov 6, 2022

peterzhu2118 Nov 3, 2022

BurdetteLamar Nov 6, 2022

peterzhu2118 Nov 6, 2022

BurdetteLamar Nov 6, 2022

peterzhu2118 Nov 6, 2022

BurdetteLamar Nov 6, 2022

peterzhu2118 Nov 6, 2022

BurdetteLamar Nov 6, 2022

peterzhu2118 Nov 6, 2022

BurdetteLamar Nov 6, 2022

peterzhu2118 Nov 6, 2022

BurdetteLamar Nov 6, 2022

BurdetteLamar commented Nov 6, 2022

BurdetteLamar commented Nov 6, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

BurdetteLamar commented Nov 8, 2022

peterzhu2118 left a comment

BurdetteLamar commented Nov 9, 2022

BurdetteLamar commented Nov 9, 2022

peterzhu2118 left a comment

peterzhu2118 commented Nov 9, 2022

BurdetteLamar commented Nov 9, 2022

peterzhu2118 commented Nov 9, 2022

BurdetteLamar commented Nov 9, 2022

	- IO#pos=: Sets the position of the stream to a given integer +new_position_ (in bytes):
	- IO#pos=: Sets the position of the stream to a given integer +new_position_ (in bytes).

	* see {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number]:
	* see {Line Number}[rdoc-ref:io_streams.rdoc@Line+Number].

		* returns +self+.
		* does nothing if already at end-of-stream;

[DOC] Enhanced RDoc for IO #6669

[DOC] Enhanced RDoc for IO #6669

Conversation

BurdetteLamar commented Nov 3, 2022

peterzhu2118 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

BurdetteLamar commented Nov 6, 2022

BurdetteLamar commented Nov 6, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

peterzhu2118 commented Nov 7, 2022

BurdetteLamar commented Nov 7, 2022

BurdetteLamar commented Nov 8, 2022

peterzhu2118 left a comment

Choose a reason for hiding this comment

BurdetteLamar commented Nov 9, 2022

BurdetteLamar commented Nov 9, 2022

peterzhu2118 left a comment

Choose a reason for hiding this comment

peterzhu2118 commented Nov 9, 2022

BurdetteLamar commented Nov 9, 2022

peterzhu2118 commented Nov 9, 2022

BurdetteLamar commented Nov 9, 2022