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

Type: CSR
Component: tools
Sub-Component: javadoc(tool)

Priority: P3
Status: Closed
Resolution: Approved
Fix Versions: 20

Submitted: 2022-05-06
Updated: 2022-06-03
Resolved: 2022-06-02

Summary
-------

Update the `{@value reference}` tag to provide a format string to be given to format the value in documentation.

Problem
-------

It is sometimes convenient to be able to override the default presentation of the value referenced in an `{@value}` tag. This is most obvious for integer values, for which it may be desirable to show the values in octal or hexadecimal format.

Solution
--------

Extend the definition of the `{@value}` tag to allow an optional
_format string_, as defined in the `java.util.Formatter` class.


Specification
-------------

The API changes for `ValueTree` and `DocTreeScanner` are given in
the attached spec diff. The latest version is available 
[here](http://cr.openjdk.java.net/~jjg/8286101/specdiff.01/overview-summary.html).

The tag specification is amended to allow an optional format string:

* `{@value` _format_ _package_`.`_class_`#`_field_ `}`

The _format_ string may be omitted, in which case a default format will be used, appropriate to the type of the field. If the _format_ string is given, it must either begin with a percent character (`%`) or be enclosed in double-quote characters (`"`). It must contain exactly one percent character. The string must conform to the definition of a format string, as specified in the documentation for `java.util.Formatter`.  The _conversion_ specified in the format string must be appropriate for the type of the constant.

Moving updated request to Approved.
02-06-2022
Added text: The conversion specified in the format string must be appropriate for the type of the constant.
01-06-2022
Could always add support for non-numeric constants later if there is a use case.
26-05-2022
Is there any use for the feature for non-numeric constants? Should we limit the feature to numeric constants only?
26-05-2022
Yes, I think some guidance on "numerical formats can be used on numerical constants", and "Foo" formats can be used for string constant, or "numerical and general format on numerical constants," whatever is intended.
26-05-2022
There is no intent to change the set of types for which you can use `{@value}`. Before this patch, and still now, you cannot use `{@value}` on enum constants. That would be a separate RFE, if it even makes sense. There is no intent to support "mismatched" format "conversion" characters, such as using an integer conversion character for a string constant. I could add an explicit statement to that effect.
26-05-2022
Moving to Provisional, not Approved. The traditional examples for @-value show that a string-valued field can be used. For the rule that @-value "Displays constant values." do enum constants count as "constant" for this purpose? If I'm interpreting the spec for the revised @-value as written, I think the 'b' and 'h' format coulds be used on at least string values and possible enum constants. That isn't necessarily a problem, but I wanted to verify if that was intended as part of the scope.
26-05-2022
1. While free text typically comes last, this is more like an option. And yes, looking to resemble String.format was intentional. 2. You can always put adjoining characters in the doc comment. While we are leveraging the ability of String.format to format the constant value, we are not providing a general purpose format string. The intent and primary use case is to control the display of "simple" single constant values -- effectively to display octal and hex integer values, and maybe control the display of floating point values.
25-05-2022
The restriction for "exactly one percent character" prohibits newlines and the percent character itself. While the newline is a bit too much, I can imagine a correct format string containing multiple % characters being copy-pasted as this tag's argument.
24-05-2022
I wonder what was the rationale for putting the optional format parameter first. Usually, a free text parameter goes last. Did you want that syntax to resemble calls to String's format(ted)?
24-05-2022