Re-specification and re-abstraction

[Joe Darcy]

On 12/22/2011 4:10 PM, David Holmes wrote:
> On 23/12/2011 8:14 AM, Brian Goetz wrote:
>>> So the scenario that current semantics is trying to serve best is the
>>> following:
>>>
>>> // author X creates:
>>>
>>> interface A {
>>> void m() defaut { ... }
>>> }
>>>
>>> // then comes user Y and extends A:
>>>
>>> interface AExt extends A {
>>> /**
>>> * Just Some JavaDoc...
> Aside: do we have any real world example where "just some javadoc" does
> not affect the actual semantic specification of the method? I guess the
> addition of doc tags would be one case.

Yes!  I added some javadoc like that to several portions of the JSR 269 
APIs shipped in JDK 7.  Originally the Element.getEnclosingElement 
method specified the behavior of the method in subtypes:

> Returns the innermost element within which this element is, loosely 
> speaking, enclosed.
>
>     * If this element is one whose declaration is lexically enclosed 
> immediately within the declaration of another element, that other 
> element is returned.
>     * If this is a top-level type, its package is returned.
>     * If this is a package, null is returned.
>     * If this is a type parameter, null is returned. 
http://docs.oracle.com/javase/6/docs/api/javax/lang/model/element/Element.html#getEnclosingElement()

In JDK 7, I added no-op overrides of getEnclosingElement to the various 
subinterfaces of Element to also give the behavior on the type in 
question as well as on the root type:

http://docs.oracle.com/javase/7/docs/api/javax/lang/model/element/TypeElement.html#getEnclosingElement()
http://docs.oracle.com/javase/7/docs/api/javax/lang/model/element/PackageElement.html#getEnclosingElement()
http://docs.oracle.com/javase/7/docs/api/javax/lang/model/element/TypeParameterElement.html#getEnclosingElement()

-Joe