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 <[email protected]> on behalf of
Markus KARG <[email protected]>
*Sent:* Sunday, February 8, 2026 9:57 AM
*To:* 'core-libs-dev' <[email protected]>
*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
