> 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.
