Re: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v8]
> 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 with a new target base due to a merge or a rebase. The pull request now contains 51 commits: - Merging master into JDK-8250768 - Removing unnecessary property keys. - Cleanup - removing unnecessary code. - Merging master into JDK-8250768-dev4 - Reflecting review comments. - Removing trailing whitespace. - Merging master into JDK-8250768. - Updating tests after records are a final feature. - Fixing tests. - Finalizing removal of record preview hooks. - ... and 41 more: https://git.openjdk.java.net/jdk/compare/700447f7...3d55f909 - Changes: https://git.openjdk.java.net/jdk/pull/703/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=07 Stats: 3665 lines in 136 files changed: 2701 ins; 692 del; 272 mod Patch: https://git.openjdk.java.net/jdk/pull/703.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/703/head:pull/703 PR: https://git.openjdk.java.net/jdk/pull/703
Re: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v9]
> 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: Removing obsolette @PreviewFeature. - Changes: - all: https://git.openjdk.java.net/jdk/pull/703/files - new: https://git.openjdk.java.net/jdk/pull/703/files/3d55f909..370031f0 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=08 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=07-08 Stats: 10 lines in 5 files changed: 0 ins; 10 del; 0 mod Patch: https://git.openjdk.java.net/jdk/pull/703.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/703/head:pull/703 PR: https://git.openjdk.java.net/jdk/pull/703
Re: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v10]
> 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 typo. - Changes: - all: https://git.openjdk.java.net/jdk/pull/703/files - new: https://git.openjdk.java.net/jdk/pull/703/files/370031f0..097ae3c1 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=09 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=703&range=08-09 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/703.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/703/head:pull/703 PR: https://git.openjdk.java.net/jdk/pull/703
RFR: JDK-8248566: Make API docs more usable on mobile browsers
The purpose of this change is to make javadoc generated pages more usable on devices with smaller screens such as phones and tablets. Changes are mostly in `stylesheet.css` along with a few small changes in generated HTML pages. - A `viewport` meta tag is added to every page to tell browsers that the page is optimized for small screens and shouldn't be rendered using desktop dimensions and scaled down to actual browser size. - The right-floating `about-language` element is moved forward before the list of main navigation links, and the display style of that list is changed to `block`. This allows the navigation links to wrap around the `about-language` div when space gets tight. Also, navigation `height` entries are changed to `min-height` so they can grow when broken to more than one line. - Media queries are added to slightly shrink various page components for smaller browser widths. This includes the search input, navigation bar fonts and various spacings within the page. API docs rendered with this change can be viewed here (overview and java.base module pages only): http://cr.openjdk.java.net/~hannesw/8248566/api.02/ The page should look the same as before the change when viewed in a normal-sized desktop browser. The changes should be visible when resizing the browser window, viewing the page with a mobile browser emulator (available in developer tools of various desktop browsers) or viewing the page on a mobile device. - Commit messages: - Merge openjdk master - Tweak styles to minimize changes in desktop view - JDK-8248566 Add styles for mobile browsers Changes: https://git.openjdk.java.net/jdk/pull/1008/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1008&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8248566 Stats: 81 lines in 4 files changed: 70 ins; 6 del; 5 mod Patch: https://git.openjdk.java.net/jdk/pull/1008.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/1008/head:pull/1008 PR: https://git.openjdk.java.net/jdk/pull/1008
Re: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v6]
On Wed, 4 Nov 2020 19:40:33 GMT, Jan Lahoda wrote: >> I have read all the files. >> >> I have added a n umber of various minor non-blocking comments (no need for >> re-review( to fix these. But I have a couple of comments/questions before >> finally giving approval. >> There's a comment in `PreviewListWriter` about annotation members that needs >> too be addressed, and I wonder is RECORD and RECORD_COMPONENT need to be >> added into PreviewElementKind. > > Thanks @jonathan-gibbons for your comments! I've tried to update the code > based on them, mostly in > https://github.com/lahodaj/jdk/commit/743f516c660b577035cdda4510a0bb97937fd9b2 > and > https://github.com/lahodaj/jdk/commit/e4b02827998fc2e8f19f983aabfb3d720b03d111 > > A big chunk of the update is generalization of the deprecated and preview > list builders and writers into a "summary" list builder and writer. These > should also now handle records. For record components, those are a little > tricky, as (AFAIK) can't currently have deprecation/preview-ness for them > (and hence there is no good way to test any support for record components in > these). But the summary build and writer are looking for record components > and will fail in case a record component is sent into them. FWIW, a javadoc generated with the current version of the patch: http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.01/api/index.html And a specdiff comparing it to the javadoc built from the corresponding master: http://cr.openjdk.java.net/~jlahoda/8250768/jdk.javadoc.specdiff.01/overview-summary.html - PR: https://git.openjdk.java.net/jdk/pull/703
Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v2]
On Wed, 4 Nov 2020 20:57:06 GMT, Jonathan Gibbons wrote:
>> This introduces support for a new `@spec` tag that can be used as either an
>> inline tag or as a block tag. It is used to identify references to external
>> specifications, in such a way that the references can be collected together
>> on a new summary page, called "Other Specifications", available from either
>> the static INDEX page or the interactive search box.
>>
>> As an inline tag, the format is `{@spec url label}`, which is roughly
>> translated to `label` in the generated docs.
>>
>> As a block tag, the format is simply
>>
>> @spec url label
>>
>> which is handled in a manner analogous to
>>
>> @see label
>>
>> The tag is notable for being the first standard/supported tag that can be
>> used as either an inline or block tag. (We have had support for bimodal
>> non-standard/custom tags for a while, such as `{@jls}` and `{@jvms}`.) To
>> support bimodal standard tags, some changes to `DocCommentParser` are
>> incorporated here.
>>
>> This change is only the _support_ for the new tag; it does _not_ include
>> any changes to API docs to _use_ the new tag.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a
> merge or a rebase. The pull request now contains 11 commits:
>
> - Fix merge issues; review feedback
> - Merge with master
> - allow rich content in createAnchorAndSearchIndex
> - update Docs.gmk to stop disabling spec tag
> - fix TestSpecTag.testEncodedURI
> - fix tests
> - remove support to workaround legacy @spec tag
> - Merge remote-tracking branch 'upstream/master' into new-spec-tag
> - fix trailing whitespace in test
> - temporarily allow existing legacy usage `@spec JPMS` `@spec jsr-51`
> - ... and 1 more:
> https://git.openjdk.java.net/jdk/compare/804bd725...ed5512d9
src/jdk.compiler/share/classes/com/sun/source/util/DocTreeFactory.java line 309:
> 307: * Creates a new {@code SpecTree} object, to represent a {@code
> @spec} tag.
> 308: *
> 309: * @param inline whether this is instance is an inline tag
Should be:
`* @param inline whether this instance is an inline tag`
-
PR: https://git.openjdk.java.net/jdk/pull/790
RFR: JDK-8254893: Fix display of search tag results without holder information
This is a trivial fix to only display holder information for index items in search results if it is available. - Commit messages: - JDK-8254893: Fix display of search tag results without holder information Changes: https://git.openjdk.java.net/jdk/pull/1077/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=1077&range=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8254893 Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/1077.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/1077/head:pull/1077 PR: https://git.openjdk.java.net/jdk/pull/1077
Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec) [v2]
On Wed, 4 Nov 2020 20:57:06 GMT, Jonathan Gibbons wrote:
>> This introduces support for a new `@spec` tag that can be used as either an
>> inline tag or as a block tag. It is used to identify references to external
>> specifications, in such a way that the references can be collected together
>> on a new summary page, called "Other Specifications", available from either
>> the static INDEX page or the interactive search box.
>>
>> As an inline tag, the format is `{@spec url label}`, which is roughly
>> translated to `label` in the generated docs.
>>
>> As a block tag, the format is simply
>>
>> @spec url label
>>
>> which is handled in a manner analogous to
>>
>> @see label
>>
>> The tag is notable for being the first standard/supported tag that can be
>> used as either an inline or block tag. (We have had support for bimodal
>> non-standard/custom tags for a while, such as `{@jls}` and `{@jvms}`.) To
>> support bimodal standard tags, some changes to `DocCommentParser` are
>> incorporated here.
>>
>> This change is only the _support_ for the new tag; it does _not_ include
>> any changes to API docs to _use_ the new tag.
>
> Jonathan Gibbons has updated the pull request with a new target base due to a
> merge or a rebase. The pull request now contains 11 commits:
>
> - Fix merge issues; review feedback
> - Merge with master
> - allow rich content in createAnchorAndSearchIndex
> - update Docs.gmk to stop disabling spec tag
> - fix TestSpecTag.testEncodedURI
> - fix tests
> - remove support to workaround legacy @spec tag
> - Merge remote-tracking branch 'upstream/master' into new-spec-tag
> - fix trailing whitespace in test
> - temporarily allow existing legacy usage `@spec JPMS` `@spec jsr-51`
> - ... and 1 more:
> https://git.openjdk.java.net/jdk/compare/804bd725...ed5512d9
1. Thanks for incorporating my previous offline feedback.
2. Since Hannes and Erik seem to have looked at everything else, I looked
mostly at changes in `src/jdk.compiler/share/classes/com/sun/source/**`, which
are good!
3. There should be a corresponding but separate change to "Documentation
Comment Specification for the Standard Doclet".
4. Can we use this new `@since` tag to refer to the spec at
`com/sun/tools/javac/parser/DocCommentParser.java:1116`?
5. Should we specify in `com.sun.source.doctree.SpecTree` that both `url` and
`label` parts are mandatory?
6. `DCSpec extends DCEndPosTree`, sigh... Although that is not a public API,
this design suggests we could improve that abstraction sometime later.
src/jdk.compiler/share/classes/com/sun/tools/javac/parser/DocCommentParser.java
line 1104:
> 1102:
> 1103: DCTree parse(int pos, Kind kind) throws ParseException {
> 1104: if (kind != this.kind && this.kind != Kind.EITHER) {
This condition looks right, but shouldn't we add another one to guard against
accidental passing of `kind == EITHER`?
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java
line 306:
> 304: * The {@code ref} argument will be URL-encoded for use as the
> attribute value.
> 305: *
> 306: * @param ref the value for the {@code href} attribute}
Since you are here, could you please remove that trailing `}`?
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/HtmlTree.java
line 322:
> 320: * {@link URI#toASCIIString() converted} to ASCII for use as the
> attribute value.
> 321: *
> 322: * @param ref the value for the {@code href} attribute}
One more, perhaps copy-pasted, trailing `}`.
test/langtools/tools/javac/diags/examples/NoLabel.java line 2:
> 1: /*
> 2: * Copyright (c) 2012, 2020 Oracle and/or its affiliates. All rights
> reserved.
Should be:
`Copyright (c) 2012, 2020, Oracle and/or its affiliates. All rights reserved.`
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/TagletWriterImpl.java
line 266:
> 264: }
> 265:
> 266: String textOf(List trees) {
I wonder if this method should work **recursively** rather than shallowly.
Consider the following example:
@spec http://example.com Some code: {@code text}
I reckon we'll end up with only `Some code: `.
src/jdk.compiler/share/classes/com/sun/tools/javac/tree/DCTree.java line 81:
> 79: return list.stream().allMatch(DCTree::isBlank);
> 80: }
> 81:
Adding these two methods **here** might be overkill.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/taglets/TagletManager.java
line 737:
> 735:
> 736: for (Taglet t : taglets) {
> 737: String name = t.isBlockTag() ? "@" + t.getName() : "{@" +
> t.getName() + "}";
Out of curiosity, why did you flip that?
-
Changes requested by prappo (Reviewer).
PR: https://git.openjdk.java.net/jdk/pull/790
