On Mon, 7 Apr 2025 18:08:29 GMT, Stuart Marks <sma...@openjdk.org> wrote:
>> src/java.base/share/classes/java/lang/IO.java line 45:
>>
>>> 43: * UTF-8 is used instead. These internal objects are created upon the
>>> first call to
>>> 44: * either of the {@code readln} methods and are stored for subsequent
>>> reuse by these
>>> 45: * methods.
>>
>> @stuart-marks Can we rephrase this paragraph so that it doesn't use phrase
>> "internal objects"? The class does speak of buffering and how it might
>> impact code that mixes use of System.in and IO.readln so I agree with that
>> part it's just the "internal objects" phrase that is confusing to read in
>> this class.
>
> I used "internal objects" because I wanted to avoid naming concrete classes,
> which might or might not be used. Previous drafts mentioned BufferedReader,
> InputStreamReader, and CharsetDecoder.
>
> I could replace "internal objects" with something more descriptive like
> "objects to handle buffering and charset decoding" but I'd still need a noun
> phrase to refer to them later. Maybe "buffering and decoding objects" ?
Can we rephrase the 1st sentence to read:
"The `readln()` and `readln(String)` methods in this class decode bytes read
from `System.in` into characters."
And remove the last "these internal objects" sentence.
And for the next paragraph, change the first line to:
"The `readln` methods may buffer additional bytes..."
So we remove references to "internal objects."
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/24438#discussion_r2031815564
