RFR: JEP 359-Records: javadoc code

[Jonathan Gibbons]

Please review a moderately small update to the proposed support for 
records in javadoc.

The primary change is to include record components in the signature of a 
record displayed near the top of the page.

In addition, a "combo test" is added into TestRecordTypes.java to verify 
the presence or absence of annotations in various places in the 
generated page for a record, depending on the `@Target` of the annotations.

Finally, there are some small cosmetic changes, and the supporting files 
for some previously published examples.

Two webrevs are provided.

The first is a cumulative webrev of the modified javadoc source and test 
files, compared against the default branch of the amber repo (i.e. the 
state of the jdk/jdk repo)
http://cr.openjdk.java.net/~jjg/amber-records/webrev.default/

The second is a "delta webrev" of the recently modified javadoc source 
and test files, compared against the tip of the records branch of the 
amber repo.
http://cr.openjdk.java.net/~jjg/amber-records/webrev.tip/

Also, the sets of examples are updated, showing examples linked and not 
linked to JDK API docs
http://cr.openjdk.java.net/~jjg/amber-records/examples/api-with-link/
http://cr.openjdk.java.net/~jjg/amber-records/examples/api-no-link/

Finally, I note a curiosity, arising from the proposed spec.  This is 
the first occurrence that I can think of in which an item that is 
syntactically necessary in the source code does /not/ show up in the 
same place in the generated documentation.  In general, in previous 
instances where the documented signatures differ from the source code, 
the difference has been the addition of default or mandated elements.  
Here, the presence of an annotation on the declaration of a record 
component in source code may not show up in the corresponding place in 
the documented signature, depending on the specified @Target for the 
annotation. I'm not saying that's wrong, but it is curious, and may need 
explaining to some.

-- Jon

JEP 359: https://openjdk.java.net/jeps/359