Updated Draft specs for JEP 359 (Records)

[Alex Buckley]

// Cutting amber-dev

On 11/25/2019 3:23 PM, Gavin Bierman wrote:
> http://cr.openjdk.java.net/~gbierman/jep359/jep359-20191125/specs/records-jls.html

The JLS draft is good. Some technical rewordings:

1. 8.10.3: "and the type as the declared type" -- missing a "same"

2. 8.10.3: Say "This field is annotated with the annotations, if any, 
that appear on the corresponding record component and whose annotation 
types are applicable in the field declaration context or in type 
contexts or both."  (Later, for implicitly declared accessor methods, 
the phrase "whose annotation type is" should be "whose annotation types 
are". We do not constrain all the annotations to have the same 
annotation type, nor all the annotation types to be applicable in the 
same way. You could introduce an existential qualifier if you like -- 
"For each annotation A that appears on the corresponding ..." -- but I 
don't think it's necessary.)

3. 8.10.3: "A method ***declared*** in a record type R is said to be an 
accessor method" -- this raises questions of "explicitly or implicitly". 
It's too easy to think it means "explicitly" when that's not always 
true. Sidestep the problem by speaking more directly: "In a record type 
R, an _accessor method for a record component_ is a method whose name is 
the same as the name of the record component, and whose formal parameter 
list is empty." Then some refactoring because long list items are hard 
to follow:

-----
For each record component appearing in the record component list:
1. An implicitly declared private final field ...
2. An accessor method for the record component. [THAT'S IT. DON'T RULE 
ON THE FORM OF EXPLICITLY DECLARED METHODS HERE. JUST MAKE SURE ALL THE 
METHODS EXIST:]

    If an accessor method for the record component is not explicitly 
declared, then one is implicitly declared with the following properties:
    - The name is the same as ...
    - ...

    It is a compile-time error if the implicitly declared accessor 
method is override-equivalent (8.4.2) with a non-private method of the 
class Object. [THIS PARAGRAPH IS TROUBLE. PLEASE MAKE AN EXPLICIT RULE 
IN 8.10.1 THAT SPELLS OUT IN CLEAR NORMATIVE TEXT THAT A RECORD 
COMPONENT MUST NOT HAVE BE CALLED CLONE, FINALIZE, ETC. RELYING ON A 
SUBTLE RULE IN A DIFFERENT SECTION ABOUT IMPLICITLY DECLARED STUFF IS 
*TOO HARD*. IT SUGGESTS THAT THE COMPILER SHOULD POSITION THE CARET FOR 
THE ERROR AT SOME POINT IN THE RECORD'S BODY, WHERE THE IMP.DECL. METHOD 
WOULD LIVE, RATHER THAN IN THE RECORD'S HEADER.]

[ITEM 2 ENDS HERE. NON-LIST TEXT FOLLOWS.]

If an accessor method for a record component is declared explicitly, 
then it must satisfy the following rules, or else a compile-time error 
occurs:
- The return type of the accessor method ...
- ...

[THE FOLLOWING PARAGRAPH IS DISTINCTLY SURE -- "IS NOT ANNOTATED" -- 
THAT AN EXPLICIT METHOD HAS NO ANNOTATIONS LIKE THE ONES ON THE RECORD 
COMPONENT. WHAT IF THE DEVELOPER WRITES ANNOTATIONS EXPLICITLY? PLEASE 
CHANGE THE PARAGRAPH TO AN INFORMATIVE NOTE WHERE YOU CAN SAY: 
ANNOTATIONS THAT APPEAR ON THE CORRESPONDING RECORD COMPONENTS ARE NOT 
CARRIED OVER TO EXPLICITLY DECLARED ACCESSOR METHODS, IN CONTRAST TO HOW 
IMPLICITLY DECLARED ACCESSOR METHODS ARE ANNOTATED ACCORDING TO BLAH BLAH.]
An explicitly declared accessor method is not annotated with any 
applicable annotation that appears on the corresponding record component.
-----

4. 8.10.4: It's odd to see in "derived constructor signature" that a 
ctor has a name R, since 8.8 doesn't admit to a ctor having a name. That 
said, 8.8.2 speaks of "two constructors with override-equivalent 
signatures (§8.4.2) in a class", and the definition of override 
equivalent implies a name is present, so I'll set my concern aside. Just 
a minor rewording for flow -- push derivation of formal parameter list 
down one level, as it's not used by anything else (OK, one place, but 
I'll get to that) :

-----
To support proper ... corresponding to the record components.

A record type R has a derived constructor signature with the name R, 
with no type parameters, and with a formal parameter list that is 
derived from the record component list of R as follows:

- For each record component ...
-----

8.10.5: Construct good things, or else people will wonder:  "At most one 
compact constructor declaration can be declared for a record type." + 
"In a record type R, the signature of a compact constructor declaration 
is the _derived constructor signature_ of R (8.10.4)."   Don't say in 
normative text that "one which is derived from the record component list 
of R is added implicitly" -- "added" is too imperative -- this is an 
opportunity to write an informative note that compares and contrasts a 
compact ctor with all other ctors in Java -- "Unlike ctors in records, 
and indeed in classes in general, no explicit formal parameter list is 
given for a compact ctor. The record component list provides the X from 
which a Y is derived."

Alex