Clarification on JavaDoc Writer::append(CharSequence)

[Alan Bateman]

On 08/02/2026 15:57, Markus KARG wrote:
> Dear Core-Lib Devs,
>
> the JavaDocs of Writer::append(CharSequence) literally says:
>
>      * <p> An invocation of this method of the form {@code 
> out.append(csq)}
>      * when {@code csq} is not {@code null}, behaves in exactly the 
> same way
>      * as the invocation
>      *
>      * {@snippet lang=java :
>      *     out.write(csq.toString())
>      * }
>      * ...
>
> I am kindly asking for an authoritative clarification how this is to 
> be understood:
>
> * (A) ONLY the particular implementation found in Writer.java MUST 
> invoke "csq.toString"?
>
> * (B) OpenJDK's OWN subclasses of Writer MUST invoke "csq.toString"?
>
> * (C) ALL subclasses of Writer (even third-party code) MUST invoke 
> "csq.toString"?
>
> * (D) ...?...

It just means that out.append(csq) and out.write(csq.toString()) are 
equivalent when csq is not null. It does not mean that every 
implementation must invoke csq.toString(). Writer.nullWriter is the 
extreme in that it can ignore csq. With specs like this then implicit 
assumption that the toString doesn't have observable side effects.

-Alan