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.

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.