[DOC] Add link targets #6602
[DOC] Add link targets #6602
Conversation
doc/io_streams.rdoc
Outdated
| may begin mid-line: | ||
|
|
||
| f = File.new('t.txt') | ||
| f.pos = 19 | ||
| f.readlines # => ["ine\n", "\n", "Fourth line\n", "Fifth line\n"] | ||
| f.readlines # => [] |
There was a problem hiding this comment.
I think the indentations of these lines need to be adjusted.
doc/io_streams.rdoc
Outdated
| @@ -368,13 +406,21 @@ which is the non-negative integer line number | |||
| in the stream where the next read will occur. | |||
|
|
|||
| The line number is the number of lines read by certain line-oriented methods | |||
| (IO.foreach, IO#each_line, IO#gets, IO#readline, and IO#readlines) | |||
| ({#foreach}[https://docs.ruby-lang.org/en/master/IO.html#method-c-foreach], | |||
There was a problem hiding this comment.
I think foreach is a class method, so I think the convention is to use ::foreach.
There was a problem hiding this comment.
Done. I'll add something to the guide about this. We've been using Foo.bar when the class name is prefixed but ::bar when not.
Well, I've started with Another problem is that adding full method doc will, by enlarging each method section, spread out the methods, so that for, say "Line IO," the reader gets no sense of overview, which was the goal of the section in the first place. No doubt further problems lurk (unknown unknowns). I'm thinking that maybe we should abandon this page (it hasn't been released yet, right?), and move everything over to class IO. Then the full methods doc can live in its usual places (where the call-seqs are), and the class header material can treat the topics (as in this page). I have no problem losing some of my effort here; better to get this right the first time. @peterzhu2118, @jeremyevans (also, anyone else): Thoughts? |
|
On second thought, maybe this page can be saved. The troubles began when I tried to import full doc for methods. Without those, maybe the page would be ok -- but that would mean backing out this merge, which we won't need. I'll think on it. |
This is battlespace preparation for making this page house the primary documentation for each stream-oriented method that appears in more than one class: e.g., gets, readlines.
The doc for the streaming classes (ARGF, File, IO, StringIO) will need to link the the individual methods here. Therefore I've reformatted each method's list item as a level-5 heading, which rdoc always recognizes as a link target (and always includes in the page's table of contents).
The next steps will be to: