8339852: Fix typos in java.compiler documentation #20937
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -202,7 +202,7 @@ public enum SourceVersion { | |
| * @see <a href="https://openjdk.org/jeps/213"> | ||
| * JEP 213: Milling Project Coin</a> | ||
| */ | ||
| RELEASE_9, | ||
|
|
||
| /** | ||
| * The version introduced by the Java Platform, Standard Edition | ||
|
|
@@ -470,7 +470,7 @@ private static SourceVersion getLatestSupported() { | |
| * | ||
| * @apiNote This method is included alongside {@link latest} to | ||
| * allow identification of situations where the language model API | ||
| * is running on a platform version different from the latest | ||
| * version modeled by the API. One way that sort of situation can | ||
| * occur is if an IDE or similar tool is using the API to model | ||
| * source version <i>N</i> while running on platform version | ||
|
|
@@ -496,8 +496,7 @@ public static SourceVersion latestSupported() { | |
| * followed only by characters for which {@link | ||
| * Character#isJavaIdentifierPart(int)} returns {@code true}. | ||
| * This pattern matches regular identifiers, keywords, contextual | ||
| * keywords, boolean literals, and the null literal. | ||
|
There was a problem hiding this comment. I don't think it is necessarily more clear remove the explicit listing of the strings in question. There was a problem hiding this comment. Perhaps. I just thought that it's strange to spell them out only here, but refer to them through "x literal(s)" everywhere else in that file. |
||
| * | ||
| * The method returns {@code false} for all other strings. | ||
| * | ||
|
|
@@ -590,14 +589,14 @@ public static boolean isName(CharSequence name, SourceVersion version) { | |
| } | ||
|
|
||
| /** | ||
| * Returns whether or not {@code s} is a keyword, a boolean literal, | ||
| * or the null literal in the latest source version. | ||
| * This method returns {@code false} for <i>contextual | ||
| * keywords</i>. | ||
| * | ||
| * @param s the string to check | ||
| * @return {@code true} if {@code s} is a keyword, boolean | ||
| * literal, or the null literal, {@code false} otherwise. | ||
| * @jls 3.9 Keywords | ||
| * @jls 3.10.3 Boolean Literals | ||
| * @jls 3.10.8 The Null Literal | ||
|
|
@@ -607,15 +606,15 @@ public static boolean isKeyword(CharSequence s) { | |
| } | ||
|
|
||
| /** | ||
| * Returns whether or not {@code s} is a keyword, a boolean literal, | ||
| * or the null literal in the given source version. | ||
| * This method returns {@code false} for <i>contextual | ||
| * keywords</i>. | ||
| * | ||
| * @param s the string to check | ||
| * @param version the version to use | ||
| * @return {@code true} if {@code s} is a keyword, boolean | ||
| * literal, or the null literal, {@code false} otherwise. | ||
| * @jls 3.9 Keywords | ||
| * @jls 3.10.3 Boolean Literals | ||
| * @jls 3.10.8 The Null Literal | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| /* | ||
| * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved. | ||
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| * | ||
| * This code is free software; you can redistribute it and/or modify it | ||
|
|
@@ -47,7 +47,7 @@ public interface AnnotationMirror { | |
|
|
||
| /** | ||
| * Returns the values of this annotation's elements. | ||
| * These are returned in the form of a map that associates elements | ||
| * with their corresponding values. | ||
| * Only those elements with values explicitly present in the | ||
| * annotation are included, not those that are implicitly assuming | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| /* | ||
| * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved. | ||
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| * | ||
| * This code is free software; you can redistribute it and/or modify it | ||
|
|
@@ -34,7 +34,7 @@ | |
| * elements. | ||
| * Annotation interface elements are methods restricted to have no | ||
| * formal parameters, no type parameters, and no {@code throws} | ||
| * clause, among other restrictions; see JLS {@jls 9.6.1} for details. | ||
| * | ||
| * @see ExecutableType | ||
| * @since 1.6 | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -58,14 +58,14 @@ | |
| * javax.lang.model.util.Elements#getFileObjectOf(Element) reference | ||
| * representation} (either source code or executable output). Multiple | ||
| * classes and interfaces can share the same reference representation | ||
| * backing construct. For example, multiple classes and interfaces can | ||
| * be declared in the same source file, including, but not limited | ||
| * to: | ||
| * <ul> | ||
| * <li> a {@linkplain NestingKind#TOP_LEVEL top-level} class or | ||
| * interface and auxiliary classes and interfaces | ||
| * <li>a top-level class or interface and {@linkplain | ||
| * NestingKind#isNested() nested classes and interfaces} within it | ||
| * </ul> | ||
| * <p>In the context of annotation processing, a type element can | ||
| * be: | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -30,7 +30,7 @@ | |
| * elements, the declared entities that make up a program. Elements | ||
| * include classes, interfaces, methods, constructors, and fields. | ||
| * The interfaces in this package do not model the structure of a | ||
| * program inside a method body; for example, there is no | ||
| * representation of a {@code for} loop or {@code try}-{@code finally} | ||
| * block. Concretely, there is no model of any abstract syntax tree | ||
| * (AST) structure of a Java program. However, the interfaces can | ||
|
|
@@ -84,7 +84,7 @@ | |
| * javax.lang.model.util.Elements#isBridge(ExecutableElement) | ||
| * bridge methods} used in implementing covariant returns, are | ||
| * translation artifacts strictly outside of this model. However, when | ||
| * operating on class files, it is helpful to be able to operate on such | ||
| * elements, screening them out when appropriate. | ||
| * | ||
| * <p>During annotation processing, operating on incomplete or | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -56,11 +56,11 @@ public interface Elements { | |
| * <ul> | ||
| * <li>find non-empty packages with the given name returned by | ||
| * {@link #getPackageElement(ModuleElement, CharSequence)}, | ||
| * where the provided ModuleElement is any | ||
| * {@linkplain java.lang.module##root-modules root module}, | ||
| * </li> | ||
| * <li>if the above yields an empty list, search | ||
| * {@linkplain #getAllModuleElements() all modules} for observable | ||
| * packages with the given name | ||
| * </li> | ||
| * </ul> | ||
|
|
@@ -143,11 +143,11 @@ default Set<? extends PackageElement> getAllPackageElements(CharSequence name) { | |
| * <ul> | ||
| * <li>find type elements with the given name returned by | ||
| * {@link #getTypeElement(ModuleElement, CharSequence)}, | ||
| * where the provided ModuleElement is any | ||
| * {@linkplain java.lang.module##root-modules root module}, | ||
| * </li> | ||
| * <li>if the above yields an empty list, search | ||
| * {@linkplain #getAllModuleElements() all modules} for observable | ||
| * type elements with the given name | ||
| * </li> | ||
| * </ul> | ||
|
|
@@ -617,7 +617,7 @@ default ModuleElement getModuleOf(Element e) { | |
|
|
||
| /** | ||
| * Returns all members of a type element, whether inherited or | ||
| * declared directly. For a class, the result also includes its | ||
| * constructors, but not local or anonymous classes. | ||
| * | ||
| * @apiNote Elements of certain kinds can be isolated using | ||
|
|
@@ -878,10 +878,10 @@ default TypeElement getEnumConstantBody(VariableElement enumConstant) { | |
| * accessor. | ||
| * | ||
| * @implSpec The default implementation of this method checks if the element | ||
| * enclosing the accessor has kind {@link ElementKind#RECORD RECORD}, if that is | ||
| * the case, then all the record components of the accessor's enclosing element | ||
| * are isolated by invoking {@link ElementFilter#recordComponentsIn(Iterable)}. | ||
| * If the accessor of at least one of the record components retrieved happens to | ||
| * be equal to the accessor passed as a parameter to this method, then that | ||
| * record component is returned, in any other case {@code null} is returned. | ||
| * | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -40,7 +40,7 @@ | |
| * ExecutableType Executable types} and the pseudo-types for | ||
| * {@linkplain TypeKind#PACKAGE packages} and {@linkplain | ||
| * TypeKind#MODULE modules} are generally out of scope for these | ||
| * methods. One or more out-of-scope arguments will typically result | ||
| * in a method throwing an {@link IllegalArgumentException}. | ||
| * | ||
| * <p>Where a method returns a type mirror or a collection of type | ||
|
|
@@ -165,7 +165,7 @@ public interface Types { | |
| * the direct supertypes of a type mirror representing {@code | ||
| * java.lang.Object}. | ||
| * | ||
| * Annotations on the direct supertypes are preserved. | ||
| * | ||
| * @param t the type being examined | ||
| * @return the direct supertypes, or an empty list if none | ||
|
|
@@ -318,7 +318,7 @@ WildcardType getWildcardType(TypeMirror extendsBound, | |
| * Annotations on the type arguments are preserved. | ||
| * | ||
| * <p> If the containing type is a parameterized type, | ||
| * the number of type arguments must be equal to the | ||
| * number of {@code typeElem}'s formal type parameters. | ||
| * If it is not parameterized or if it is {@code null}, this method is | ||
| * equivalent to {@code getDeclaredType(typeElem, typeArgs)}. | ||
|
|
@@ -354,7 +354,7 @@ DeclaredType getDeclaredType(DeclaredType containing, | |
| /** | ||
| * {@return a type mirror equivalent to the argument, but with no annotations} | ||
| * If the type mirror is a composite type, such as an array type | ||
| * or a wildcard type, any constituent types, such as the | ||
| * component type of an array and the type of the bounds of a | ||
| * wildcard type, also have no annotations, recursively. | ||
| * | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| /* | ||
| * Copyright (c) 2006, 2024, Oracle and/or its affiliates. All rights reserved. | ||
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| * | ||
| * This code is free software; you can redistribute it and/or modify it | ||
|
|
@@ -39,7 +39,7 @@ | |
| * additional fields and methods. | ||
| * | ||
| * <p>Unless stated otherwise, references in this class to "<em>this file object</em>" | ||
| * should be interpreted as referring indirectly to the {@linkplain #fileObject delegate file object}. | ||
| * | ||
| * @param <F> the kind of file object forwarded to by this object | ||
| * @since 1.6 | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| /* | ||
| * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved. | ||
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| * | ||
| * This code is free software; you can redistribute it and/or modify it | ||
|
|
@@ -39,7 +39,7 @@ | |
| * additional fields and methods. | ||
| * | ||
| * <p>Unless stated otherwise, references in this class to "<em>this file manager</em>" | ||
| * should be interpreted as referring indirectly to the {@linkplain #fileManager delegate file manager}. | ||
| * | ||
| * @param <M> the kind of file manager forwarded to by this object | ||
| * @since 1.6 | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,5 @@ | ||
| /* | ||
| * Copyright (c) 2005, 2024, Oracle and/or its affiliates. All rights reserved. | ||
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. | ||
| * | ||
| * This code is free software; you can redistribute it and/or modify it | ||
|
|
@@ -34,7 +34,7 @@ | |
| * additional fields and methods. | ||
| * | ||
| * <p>Unless stated otherwise, references in this class to "<em>this file object</em>" | ||
| * should be interpreted as referring indirectly to the {@linkplain #fileObject delegate file object}. | ||
| * | ||
| * @param <F> the kind of file object forwarded to by this object | ||
| * @since 1.6 | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -52,7 +52,7 @@ | |
| * | ||
| * <p>Some methods in this interface use class names. Such class | ||
| * names must be given in the Java Virtual Machine internal form of | ||
| * fully qualified class and interface names. For convenience, '.' | ||
| * and '/' are interchangeable. The internal form is defined in | ||
| * chapter four of | ||
| * <cite>The Java Virtual Machine Specification</cite>. | ||
|
|
@@ -239,7 +239,7 @@ Iterable<JavaFileObject> list(Location location, | |
| String inferBinaryName(Location location, JavaFileObject file); | ||
|
|
||
| /** | ||
| * Compares two file objects and returns true if they represent the | ||
| * same underlying object. | ||
| * | ||
| * @param a a file object | ||
|
|
@@ -255,7 +255,7 @@ Iterable<JavaFileObject> list(Location location, | |
|
|
||
| /** | ||
| * Handles one option. If {@code current} is an option to this | ||
| * file manager, it will consume any arguments to that option from | ||
| * {@code remaining} and return true, otherwise return false. | ||
| * | ||
| * @param current current option | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"the annotation interface of the container annotation is AIC"
or
"the containing annotation interface is AIC"
To align with the JLS.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"Type" is appropriate here and in some other locations in the
AnnotatedConstructjavadoc. I paid attention to the difference between "contain-ing annotation interface" and "contain-er annotation".@dansmithcode, please correct me if I'm wrong.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
For convenience, here's the rendered documentation in question for JDK 23: https://download.java.net/java/early_access/jdk23/docs/api/java.compiler/javax/lang/model/AnnotatedConstruct.html#:~:text=containing
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The "type" terminology is outdated and is already migrated to "class or interface" or the applicable subtype elsewhere: https://bugs.openjdk.org/browse/JDK-8257636 and commit 952dc70
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@liach, I respect you as a fellow JLS reader. Not only am I aware of that JBS issue, but I also remember the respective PR being reviewed.
Unsurprisingly, I had a similar knee-jerk reaction to the word "type". So, before publishing this PR, I asked a JLS expert on its use in this context. He replied that although in general "type" should not to be conflated with "interface"/"class", in this context it is reasonable to use "type".
However, if we do decide to abandon "type", we need to inspect every use of it in this class very carefully. The closest terminology that I could find is JLS 9.7.1
and JLS 9.6.3
Note how slightly dizzying the terminology is.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Separately, maybe JLS hasn't done its homework in full? See 9.6.4.1.
@Target:There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, that use of "type" in 9.6.4.1. feels like an overlook.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Chen, I suggest we integrate this PR as is but ask JLS experts/authors on the issue. In fact, I've already asked. I suspect that JLS 9.6.4.1 is germane to this discussion. If JLS changes "type" to "interface" in JLS 9.6.4.1, we could change these occurrences of "type" to "interface" in
AnnotatedConstructtoo.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There's really nothing wrong with talking about the type of an annotation, just like you can talk about the type of a variable. If it's the most intuitive way to express what you're trying to say, go for it!