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

[Joseph D. Darcy]

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