[core-libs] RFR (L): 8010319: Implementation of JEP 181: Nest-Based Access Control

[mandy chung]

Thanks for the explanation, Joe.  I see the subtle difference on these 
terminologies.

I'm okay with this patch.

I like the other option better to remove @apiNote since the spec states 
that the duplicates may not be removed.

Mandy

On 6/12/18 5:49 PM, Joseph D. Darcy wrote:
> On 6/11/2018 10:38 PM, mandy chung wrote:
>>
>>
>> On 6/11/18 10:16 PM, David Holmes wrote:
>>> Here is one further minor update from the CSR discussions:
>>>
>>> http://cr.openjdk.java.net/~dholmes/8010319-JEP181/webrev.corelibs.v5-incr/src/java.base/share/classes/java/lang/Class.java.cdiff.html 
>>
>>
>>
>> "This implementation" is fine, as used in many @implNote.  Any reason 
>> why it has to be changed to "reference implementation"?
>>
> 
> To summarize the concern there, the phrase "This implementation..." when 
> used elsewhere has a different meaning.
> 
> Often the phrasing "This implementation..." or the more commonly used 
> "The default implementation..." is used for text that is part of the 
> contract of a method that can be overridden; that is, used to separate 
> out the contract that is independent of which class or interface 
> provides the implementation from the contract of a particular 
> implementation.
> 
> One example from an API I work on occurs for the method 
> javax.lang.model.element.ElementVisitor.visitModule. The default method 
> defined in an interface states "The default implementation visits a 
> ModuleElement by calling visitUnknown..." and then various visitor 
> classes define their own behavior for this method while still being able 
> to @inheritDoc the general "visit a module element" contract of the 
> visitModule method.
> 
> However, java.lang.Class is final so for a particular JDK version there 
> is only one implementation of the method in question. In that context 
> "This implementation" doesn't mean "the implementation in this 
> particular class or interface as opposed to the implementation in an a 
> more specific subtype" it means "the implemetnation for the final method 
> used in a particular JDK release."
> 
> I think using the term "This implementation" in the latter context is 
> misleading so I suggested the alternative wording David sent out for 
> review.
> 
> HTH,
> 
> -Joe