RFR: JEP 359-Records: javadoc code

[Maurizio Cimadamore]

Aside from Chris comments on modifiers, I think the compact record 
signature looks great, and adds a lot of value (which will pay further 
dividends when we add pattern matching). Well done.

Annotations also look good.

Maurizio

On 30/10/2019 23:50, Jonathan Gibbons wrote:
> 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
>