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
