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

Reply via email to