On Fri, 6 Nov 2020 18:41:15 GMT, Jan Lahoda wrote:
>> This is an update to javac and javadoc, to introduce support for Preview
>> APIs, and generally improve javac and javadoc behavior to more closely
>> adhere to JEP 12.
>>
>> The notable changes are:
>>
>> * adding support for Preview APIs (javac until now supported primarily only
>> preview language features, and APIs associated with preview language
>> features). This includes:
>> * the @PreviewFeature annotation has boolean attribute "reflective",
>> which should be true for reflective Preview APIs, false otherwise. This
>> replaces the existing "essentialAPI" attribute with roughly inverted meaning.
>> * the preview warnings for preview APIs are auto-suppressed as
>> described in the JEP 12. E.g. the module that declares the preview API is
>> free to use it without warnings
>> * improving error/warning messages. Please see [1] for a list of
>> cases/examples.
>> * class files are only marked as preview if they are using a preview
>> feature. [1] also shows if a class file is marked as preview or not.
>> * the PreviewFeature annotation has been moved to jdk.internal.javac
>> package (originally was in the jdk.internal package).
>> * Preview API in JDK's javadoc no longer needs to specify @preview tag in
>> the source files. javadoc will auto-generate a note for @PreviewFeature
>> elements, see e.g. [2] and [3] (non-reflective and reflective API,
>> respectively). A summary of preview elements is also provided [4]. Existing
>> uses of @preview have been updated/removed.
>> * non-JDK javadoc is also enhanced to auto-generate preview notes for uses
>> of Preview elements, and for declaring elements using preview language
>> features [5].
>>
>> Please also see the CSR [6] for more information.
>>
>> [1]
>> http://cr.openjdk.java.net/~jlahoda/8250768/JEP12-errors-warnings-v6.html
>> [2]
>> http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.base/java/lang/Record.html
>> [3]
>> http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/java.compiler/javax/lang/model/element/RecordComponentElement.html
>> [4]
>> http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.00/api/preview-list.html
>> [5] http://cr.openjdk.java.net/~jlahoda/8250768/test.javadoc.00/
>> [6] https://bugs.openjdk.java.net/browse/JDK-8250769
>
> Jan Lahoda has updated the pull request incrementally with one additional
> commit since the last revision:
>
> Fixing navigator for the PREVIEW page.
I have a mild queasiness about this new overloaded use of the word "Summary",
since "summary tables" are normally the summary of the contents of a
declaration, like fields and methods of a class.
That being said, the usage is primarily internal, and I have no overwhelmingly
wonderful alternative, and (overloading aside) the term is accurate.
So, OK for now. We can change it later if we want to.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
line 2949:
> 2947:
> 2948: /**
> 2949: * Return the set of preview language features used to declare the
> given element.
"Returns"
-
Marked as reviewed by jjg (Reviewer).
PR: https://git.openjdk.java.net/jdk/pull/703
