RFR: 8372353: API to compute the byte length of a String encoded in a given Charset [v2]

[Roger Riggs]

On Thu, 15 Jan 2026 08:47:47 GMT, Liam Miller-Cushon <cushon at openjdk.org> wrote:

>> src/java.base/share/classes/java/lang/String.java line 2130:
>> 
>>> 2128: 
>>> 2129:     /**
>>> 2130:      * Returns the length in bytes of the given String encoded with the given {@link Charset}.
>> 
>> You can use the javadoc tag `@return` and skip the duplication.  This first sentence reads better then the @return below since it emphasies the "encoded string" aspect.
>
> Sorry I'm not sure I understand, can you clarify how that would work?
> 
> The javadoc can't start with `@return`, it needs to be a non-tag sentence fragment (the build enables doclint to enforce this).

fyi, New javadoc functionality in JDK 22 enabled @return as an inline tag.  (see the [Javadoc tag specification](https://docs.oracle.com/en/java/javase/22/docs/specs/javadoc/doc-comment-spec.html))
`As an inline tag, provides content for the first sentence of a method's main description, and a "Returns" section, as if @return description were also present. In the default English locale, the first sentence is Returns description .`

-------------

PR Review Comment: https://git.openjdk.org/jdk/pull/28454#discussion_r2694390929