RFR: JDK-8286101: Support formatting in @value tag [v3]

[ExE Boss]

On Tue, 17 May 2022 23:14:48 GMT, Jonathan Gibbons <jjg at openjdk.org> wrote:

>> This PR is for an update to the doc comment `{@value}` tag to permit an optional [format string](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/Formatter.html#syntax) after the name of the tag.
>> 
>>     {@value optional-format-string optional-reference}
>> 
>> If given, the format string should either begin with `%` or the string should be quoted with `"`. For example, `%4x` or `"0x%4x"`.  The format string must contain exactly one `%` character.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains six additional commits since the last revision:
> 
>  - fix typo
>  - Merge remote-tracking branch 'upstream/master' into 8286101.format-at-value
>  - address review feedback
>  - address review feedback
>  - Merge remote-tracking branch 'upstream/master' into 8286101.format-at-value
>  - JDK-8286101: Support formatting in @value tag

src/jdk.compiler/share/classes/com/sun/source/doctree/ValueTree.java line 51:

> 49:      *
> 50:      * @implSpec This implementation returns {@code null}.
> 51:      * @since 19

This `@since` tag is wrong (unless this will be backported to JDK 19)

src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 423:

> 421:      *
> 422:      * @implSpec This implementation calls {@link #newValueTree(ReferenceTree) newValueTree(ref)}.
> 423:      * @since 19

[ditto](https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/8565*discussion_r903643787__;Iw!!ACWV5N9M2RV99hQ!OuTpEeh3fbHm8FzfoXgKePV2FfoA_2l8eK08YcBVOdOCqCeHHSIamMBnxIgi3-yR7assxC3pxzlPlpunsiQ$ )

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

PR: https://git.openjdk.org/jdk/pull/8565