RFR: JEP 359-Records: javadoc code

[Maurizio Cimadamore]

Answering to myself here:

On 18/10/2019 13:28, Maurizio Cimadamore wrote:
>
>
> One high-level gripe which is pointing at a failure of the j.l.model 
> API is the lack of a way to get to the canonical constructor directly; 
> we have this issue both in core reflection and source reflection, and 
> I think we should address that, as both serialization and javadoc has 
> to DYI around that.


We discussed more about this offline today and we concluded that, for 
the time being, this is a non-issue, both for core reflection and for 
source reflection. These API are traditionally 'lumpy' meaning that e.g. 
records and classes have the same representation (e.g. j.l.Class and 
j.l.model.TypeElement). So, adding an extra method like 
'getCanonicalConstructor' feels yet of another of those arguable API 
moves where we add a method X which only makes sense if the predicate Y 
yields true. Moving forward we will have better ways to deal with lumpy 
APIs like these (see pattern matching) - in the meantime, we think it's 
better to leave this alone and avoid excessive pollution of the 
reflective APIs. Of course, should this ever become an usability pain 
point, we can always add helper methods later, as the records feature 
exits its preview period.

Cheers
Maurizio


>
> Maurizio
>
> On 17/10/2019 20:45, Jonathan Gibbons wrote:
>> cc: javadoc-dev at openjdk.java.net
>>
>> --Jon
>>
>>
>> On 10/17/2019 12:43 PM, Vicente Romero wrote:
>>> Hi,
>>>
>>> Please review the javadoc code for JEP 359 (Records), this webrev 
>>> contains only the javadoc code as we have decided to split the new 
>>> code in clusters to make the review process easier.
>>>
>>> Thanks in advance for the feedback,
>>> Vicente
>>>
>>> PS, Jon is the author of this code please keep him in the loop
>>>
>>> http://cr.openjdk.java.net/~vromero/records.review/javadoc/webrev.00/
>>