On Thu, 1 May 2025 19:19:32 GMT, Roger Riggs <rri...@openjdk.org> wrote:
>> src/java.base/share/classes/java/io/Reader.java line 408:
>>
>>> 406: * <p> This method works as if invoking it were equivalent to
>>> evaluating
>>> 407: * the expression:
>>> 408: * <blockquote>{@linkplain
>>> #readAllChars()}.lines().toList()</blockquote>
>>
>> I think this is actually too specific, as it could imply the returned List
>> is the exact implementation that is returned by Stream.toList(). It is in
>> this implementation, but I could easily imagine another implementation that
>> constructs the list a different way. It might be better to be descriptive
>> here and say that the entire input is read and is split into lines (where
>> "line" is defined as above) which are returned in an unmodifiable list. And
>> then have "unmodifiable list" be a link to the Unmodifiable Lists section,
>> something like "java/util/List.html#unmodifiable".
>
> The word 'equivalent' mitigates the exactness of the code to describe the
> expected result.
I think it's still ambiguous. There was a back-and-forth a while ago -- I think
@bplb was involved -- where there was similar wording about something being
"equivalent to" or "as if" foo() was called, and the person was insistent that
this meant that foo() should actually be called (and it was a bug that foo()
was not called).
A possible rewording that might tip the balance is to change "works as if"
(which implies implementation) to "the result is as if" (which emphasizes the
result and less how it was arrived at). But I'd still recommend avoiding using
code as a specification, especially if the code involves a publicly overridable
method.
-------------
PR Review Comment: https://git.openjdk.org/jdk/pull/24728#discussion_r2072031354
