Bug ID: JDK-8286101 Support formatting in @value tag

Versions (Unresolved/Resolved/Fixed)

The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.

JDK 20
20 b02Fixed

The @value javadoc tag allows a constant value to be inserted into the text. However, no formatting options over that value are provided. At times, control of formatting is essential to present the information in a useful way, such as presenting bit masks in hex rather than decimal.

(The utility of having a such a formatting feature was observed during the course of work on JDK-8266670.)

Changeset: 53a0acee Author: Jonathan Gibbons <jjg@openjdk.org> Date: 2022-06-13 18:13:21 +0000 URL: https://git.openjdk.org/jdk/commit/53a0acee06eb32fba700967c9a34d37ea42f7a99
13-06-2022
A pull request was submitted for review. URL: https://git.openjdk.java.net/jdk/pull/8565 Date: 2022-05-05 23:39:46 +0000
17-05-2022
The general idea of the proposal is that if a format string is provided, it will be used to convert the constant value to a string. The format string would be as defined for String.format and friends, and must contain a single format specifier for a value. For example, `{@value "0x%08x" MyClass#myField}`. If no format is found, the behavior is as now. It is an error if any errors are reported while trying to format the value. https://docs.oracle.com/en/java/javase/18/docs/api/java.base/java/util/Formatter.html#syntax
04-05-2022
The motivating example was to refer to java.lang.reflect.Modifier integer mask values as 4-digit hex values rather than as decimal values in a new AccessFlag enum.
04-05-2022
Brainstorming from [~jjg]: optons/suggestions: {@value "format-string" signature} {@value format="string" signature} where the format info is optional in both cases, allowing existing use to continue unchanged. Maybe a mild preference for 1 but open to discussion. Not sure how much flexibility we want/need and what constant types this can be used for
04-05-2022

CSR :	JDK-8286264 - Support formatting in @value tag
Duplicate :	JDK-8286307 - Enable {@Value...} to allow formatting of values (as hexadecimal, etc).
Relates :	JDK-8266670 - Better modeling of access flags in core reflection
Relates :	JDK-8297091 - New langtools test jdk/javadoc/doclet/testValueTag/TestValueFormats.java fails on machines with unexpected number format