RFR: 8373186: Improve readability of core reflection toString specifications

[Joe Darcy]

On Mon, 8 Dec 2025 01:14:19 GMT, Chen Liang <liach at openjdk.org> wrote:

>> Partial implementation of a spec refactoring to get some feedback before writing similar changes for other core reflection types.
>
> src/java.base/share/classes/java/lang/reflect/Field.java line 360:
> 
>> 358:      *    private int java.io.FileDescriptor.fd
>> 359:      *    public static java.util.List Foo.bar
>> 360:      * </pre>
> 
> Having such examples here means this method has a specified output that users can parse.  We should move this to some non-normative section like an implementation note.
> 
> (Don't know why github mobile didn't capture my comment before, I already commented yesterday)

Hmm. it is possible to move the examples so they are more clearly _informative_ rather than _normative_.

As a counterpoint, the toString() spec for java.lang.annotation.Annotation states:

> Returns a string representation of this annotation. The details of the representation are implementation-dependent, but the following may be regarded as typical:
> 
> `  @com.example.Name(first="Duke", middle="of", last="Java")`

Developers used this string successfully for informative purposes, even though the exact details have been changed (improved and corrected) a number of times over the years.

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

PR Review Comment: https://git.openjdk.org/jdk/pull/28688#discussion_r2600548329