Class & interface terminology

[Jonathan Gibbons]

On 5/8/20 12:02 PM, Dan Smith wrote:
>> On May 8, 2020, at 11:26 AM, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> On 5/7/20 11:48 AM, Dan Smith wrote:
>>> This isn't a one-time change. I'm sure there's more work to do in JLS and JVMS, as the need arises, and various other parts of the ecosystem (reflection APIs, javac error messages, javadoc output, JDK code internals, third-party tools, etc.) may want to similarly make changes, as needed and practical.
>> I presume we will not try and change the names of declarations in the public API, right?  Do you have any suggestions on how to "handle" these declarations, such as some boilerplate text to correlate the declared name with the standard terminology?
> Sure, what we're talking about is "preferred terminology". Where there are compatibility constraints requiring a different terminology, a change is unlikely to be worthwhile. (Any particular examples you're wondering about, though?)
>
> On the other hand, there's text like this from the java.lang.Class javadoc that could definitely use revision: "An enum type and a record type are kinds of class; an annotation type is a kind of interface."
>
> So, generally, I'd just suggest using the appropriate terminology in text, and *maybe* including a note about how API names are different "for historical reasons". (I'm not sure there's really a need most of the time, though. I don't think there's anywhere in java.lang.Class where we say "Class isn't such a great name for this abstraction, what we actually mean is ...".)
>
>> What is the expected timeline for this work to start making it into JDK releases?   For example, when should we be looking to update the javadoc tool to use the new terminology in the places where the tool is responsible for generating content?  "Annotation Type" is the primary/biggest example that comes to mind.
> As I've explained earlier in the thread, the goal here isn't really to invent some new terminology, it's to iron out inconsistencies. So I don't think there's any need to, say wait for JLS changes to be finalized before talking about "annotation interfaces" in javadoc. People should understand what that means.
>
> But I can understand wanting to wait—in which case, there's a dependency on these changes in order for records to be final. Assume that's JDK 16.
>
> On the other side, I don't think there's anything wrong with waiting. Like all technical debt, there's an opportunity, but not necessarily an obligation, to make some changes here. Fixing it *eventually* is probably a good idea, but it may not be urgent.
>
Dan,

I'm thinking of usages of the terminology in pages like this:
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Deprecated.html
(or for any other annotation-thingie)

i.e. as in this "virtual screenshot":

Module java.base 
<https://docs.oracle.com/en/java/javase/11/docs/api/java.base/module-summary.html>
Package java.lang 
<https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/package-summary.html>


    Annotation Type Deprecated

or on this page:
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/package-summary.html

Annotation Types SummaryAnnotation Type 	Description
Deprecated 
<https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/Deprecated.html> 
	
A program element annotated|@Deprecated|is one that programmers are 
discouraged from using.
FunctionalInterface 
<https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/FunctionalInterface.html> 
	
An informative annotation type used to indicate that an interface type 
declaration is intended to be a/functional interface/as defined by the 
Java Language Specification.


I guess I'm thinking that when the terminology-bikeshed has settled 
down, and you commit to a release to update JLS and JVMS, we should 
commit to update the javadoc tool in the same release. (This is 100% 
separate from updated any terminology in javadoc comments.)

-- Jon