On 5/8/20 12:02 PM, Dan Smith wrote:
On May 8, 2020, at 11:26 AM, Jonathan Gibbons <jonathan.gibb...@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
