Clarification on JavaDoc Writer::append(CharSequence)

[Markus KARG]

Chen,


thank you very much for your elaborate answer. Unfortunately it is not 
finally answering my actual question.


First of all, unfortunately, the wording is ambiguous: You wrote "...and 
all implementations", but then go on with "(C) out" - but (C) was the 
SOLE case about ALL implementations, so this is yes and no in the same line.


Second, you elaborate about @apiNote, @implSpec, and @implNote, but 
NEITHER of them is used in the mentioned JavaDocs location. Maybe you 
missed that my question is EXACTLY about that particular JavaDoc 
location BECAUSE those markers are missing?


Third, I need an AUTHORITATIVE and UNAMBIGUOUS answer, and your wording 
sounds more like an opinion.


Hence, kindly asking once more for a clear and authoritative answer: Is 
it (A), (B) or (C) for Writer::append(CharSequence)?


Thanks!

-Markus



Am 09.02.2026 um 05:06 schrieb Chen Liang:
> Hi Markus,
> A piece of API specification in the Javadoc form applies to both 
> callers and all implementations of a particular method. So here, (C) 
> out of your options.
>
> There are @apiNote, @implSpec, and @implNote Javadoc block tags that 
> indicates the scope of their text. For example, the implSpec tag 
> applies to an immediate class/method, so were this documentation in an 
> @implSpec tag, it would have been (A) out of the options.
>
> Meanwhile, the two note tags have the same scope (apiNote for all 
> implementation, implNote for particular implementation) as the 
> corresponding specs, but they are not binding and are just for 
> informative purposes, and their updates do not require CSR reviews.
>
> The scope you described in (B) is a valid scope too; I did a regex 
> search "reference\s+implementation", case-insensitive, and found that 
> most of these descriptions are in @implNote tags.
>
> Regards,
> Chen Liang
> ------------------------------------------------------------------------
> *From:* core-libs-dev <core-libs-dev-retn at openjdk.org> on behalf of 
> Markus KARG <markus at headcrashing.eu>
> *Sent:* Sunday, February 8, 2026 9:57 AM
> *To:* 'core-libs-dev' <core-libs-dev at openjdk.org>
> *Subject:* Clarification on JavaDoc Writer::append(CharSequence)
> 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) ...?...
>
> Regards
>
> -Markus Karg
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20260209/9f62d83c/attachment.htm>