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
