Integrated: JDK-8275406: Add copy-to-clipboard feature to snippet UI
On Tue, 19 Oct 2021 13:51:03 GMT, Hannes Wallnöfer wrote: > Please review a change to add a copy-to-clipboard feature to snippets. I took > special care to make the feature usable on mobile devices. Sample output can > be viewed and tested here: > > http://cr.openjdk.java.net/~hannesw/8275406/api.00/java.base/java/lang/Throwable.html#printStackTrace() This pull request has now been integrated. Changeset: 8630f55e Author:Hannes Wallnöfer URL: https://git.openjdk.java.net/jdk/commit/8630f55ed7a0483ec5dcb13a7f53b52bc4ab6fc6 Stats: 180 lines in 14 files changed: 166 ins; 0 del; 14 mod 8275406: Add copy-to-clipboard feature to snippet UI Reviewed-by: erikj, jjg - PR: https://git.openjdk.java.net/jdk/pull/6011
Re: RFR: JDK-8275406: Add copy-to-clipboard feature to snippet UI [v2]
> Please review a change to add a copy-to-clipboard feature to snippets. I took > special care to make the feature usable on mobile devices. Sample output can > be viewed and tested here: > > http://cr.openjdk.java.net/~hannesw/8275406/api.00/java.base/java/lang/Throwable.html#printStackTrace() Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision: Update copyright years - Changes: - all: https://git.openjdk.java.net/jdk/pull/6011/files - new: https://git.openjdk.java.net/jdk/pull/6011/files/8aa62cd9..b4c327c9 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=6011=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk=6011=00-01 Stats: 2 lines in 2 files changed: 0 ins; 0 del; 2 mod Patch: https://git.openjdk.java.net/jdk/pull/6011.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/6011/head:pull/6011 PR: https://git.openjdk.java.net/jdk/pull/6011
Re: RFR: JDK-8275406: Add copy-to-clipboard feature to snippet UI
On Tue, 19 Oct 2021 16:14:37 GMT, Pavel Rappo wrote:
>> Please review a change to add a copy-to-clipboard feature to snippets. I
>> took special care to make the feature usable on mobile devices. Sample
>> output can be viewed and tested here:
>>
>> http://cr.openjdk.java.net/~hannesw/8275406/api.00/java.base/java/lang/Throwable.html#printStackTrace()
>
> test/langtools/jdk/javadoc/doclet/testSnippetTag/TestSnippetTag.java line 214:
>
>> 212: case%s()
>> 213:
>> 214: > class="snippet-copy" onclick="cop\
>
> I'm sorry for hard-coding the snippet HTML output; I should've encapsulated
> it instead. Now every change to the HTML structure ripples through the tests.
> I'll work on improving that, I promise.
>
> Separately. Aren't these "Copy" and "Copied!" strings localized? What happens
> if this test is run on some other locale?
Yes, they are localized. Good question, I do believe tests are run with fixed
en/US locale, but I'm not absolutely sure.
> test/langtools/jdk/javadoc/lib/javadoc/tester/LinkChecker.java line 354:
>
>> 352: void addReference(String name, Path from, int line) {
>> 353: if (checked) {
>> 354: if (name != null && !name.isEmpty()) {
>
> I wonder if we should make this check more specific so as to allow only the
> snippet copy-to-clipboard link.
I think this should be ok for the general case. Linking to "#" (i.e. empty
fragment) is common practice for links that trigger script functions.
-
PR: https://git.openjdk.java.net/jdk/pull/6011
RFR: JDK-8275406: Add copy-to-clipboard feature to snippet UI
Please review a change to add a copy-to-clipboard feature to snippets. I took special care to make the feature usable on mobile devices. Sample output can be viewed and tested here: http://cr.openjdk.java.net/~hannesw/8275406/api.00/java.base/java/lang/Throwable.html#printStackTrace() - Commit messages: - Update TestSnippetTag.java - JDK-8223357: Fine-tune alignment - JDK-8275406: Add copy-to-clipboard feature to snippet UI Changes: https://git.openjdk.java.net/jdk/pull/6011/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk=6011=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8275406 Stats: 178 lines in 14 files changed: 166 ins; 0 del; 12 mod Patch: https://git.openjdk.java.net/jdk/pull/6011.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/6011/head:pull/6011 PR: https://git.openjdk.java.net/jdk/pull/6011
Re: RFR: 8245095: Implementation of JEP 408: Simple Web Server [v5]
On Tue, 21 Sep 2021 15:27:12 GMT, Daniel Fuchs wrote: >> I just realized I commented on a test file, while the actual culprit is in >> `FileServerHandler.java`. But I guess it applies to all usages of this class >> and method. > > Hmm... When printing messages on the console don't we want a localized date? > Or are you referring to other usages of the date formatter? Worth double > checking in any case. The problem I was referring to was not about printing to the console. I hadn't thought about that, I agree the default locale should be used there. I was referring to `Last-modified` HTTP headers with a non-English date value, e.g.: Last-modified: Di., 21 Sep. 2021 09:56:53 GMT I think browsers will get confused by this. It probably isn't a big deal since I think the server doesn't implement conditional GETs (i.e. use the last-modified date in subsequent requests), but the HTTP spec is [quite strict ][1] about date formats. [1]: https://datatracker.ietf.org/doc/html/rfc2616#section-3.3.1 - PR: https://git.openjdk.java.net/jdk/pull/5505
Re: RFR: 8245095: Implementation of JEP 408: Simple Web Server [v5]
On Tue, 21 Sep 2021 14:59:18 GMT, Hannes Wallnöfer wrote:
>> Julia Boes has updated the pull request with a new target base due to a
>> merge or a rebase. The pull request now contains 16 commits:
>>
>> - Merge branch 'master' into simpleserver
>> - Merge remote-tracking branch 'origin/simpleserver' into simpleserver
>> - Merge branch 'master' into simpleserver
>> - refactor isHidden,isReadable,isSymlink checks and cleanup tests
>> - Merge branch 'master' into simpleserver
>> - check isHidden, isSymlink, isReadable for all path segments
>> - add checks for all path segments
>> - Merge branch 'master' into componentcheck
>> - Merge branch 'master' into simpleserver
>> - improve output on startup
>> - ... and 6 more:
>> https://git.openjdk.java.net/jdk/compare/6d91a3eb...fe059131
>
> test/jdk/com/sun/net/httpserver/simpleserver/SecurityManagerTest.java line
> 198:
>
>> 196:
>> 197: static final DateTimeFormatter HTTP_DATE_FORMATTER =
>> 198: DateTimeFormatter.ofPattern("EEE, dd MMM HH:mm:ss v");
>
> I think this and other usages of `DateTimeFormatter.ofPattern` need to be
> called with `Locale.US` (or something similar) as second argument, otherwise
> the current default locale will be used. I noticed because on my laptop the
> `Last-modified` header contains a german date.
I just realized I commented on a test file, while the actual culprit is in
`FileServerHandler.java`. But I guess it applies to all usages of this class
and method.
-
PR: https://git.openjdk.java.net/jdk/pull/5505
Re: RFR: 8245095: Implementation of JEP 408: Simple Web Server [v5]
On Tue, 21 Sep 2021 14:09:54 GMT, Julia Boes wrote:
>> This change implements a simple web server that can be run on the
>> command-line with `java -m jdk.httpserver`.
>>
>> This is facilitated by adding an entry point for the `jdk.httpserver`
>> module, an implementation class whose main method is run when the above
>> command is executed. This is the first such module entry point in the JDK.
>>
>> The server is a minimal HTTP server that serves the static files of a given
>> directory, similar to existing alternatives on other platforms and
>> convenient for testing, development, and debugging.
>>
>> Additionally, a small API is introduced for programmatic creation and
>> customization.
>>
>> Testing: tier1-3.
>
> Julia Boes has updated the pull request with a new target base due to a merge
> or a rebase. The pull request now contains 16 commits:
>
> - Merge branch 'master' into simpleserver
> - Merge remote-tracking branch 'origin/simpleserver' into simpleserver
> - Merge branch 'master' into simpleserver
> - refactor isHidden,isReadable,isSymlink checks and cleanup tests
> - Merge branch 'master' into simpleserver
> - check isHidden, isSymlink, isReadable for all path segments
> - add checks for all path segments
> - Merge branch 'master' into componentcheck
> - Merge branch 'master' into simpleserver
> - improve output on startup
> - ... and 6 more:
> https://git.openjdk.java.net/jdk/compare/6d91a3eb...fe059131
test/jdk/com/sun/net/httpserver/simpleserver/SecurityManagerTest.java line 198:
> 196:
> 197: static final DateTimeFormatter HTTP_DATE_FORMATTER =
> 198: DateTimeFormatter.ofPattern("EEE, dd MMM HH:mm:ss v");
I think this and other usages of `DateTimeFormatter.ofPattern` need to be
called with `Locale.US` (or something similar) as second argument, otherwise
the current default locale will be used. I noticed because on my laptop the
`Last-modified` header contains a german date.
-
PR: https://git.openjdk.java.net/jdk/pull/5505
Re: RFR: JDK-8272374: doclint should report missing "body" comments
On Fri, 13 Aug 2021 03:51:23 GMT, Jonathan Gibbons wrote:
> Please review a relatively simple update to have doclnt check for empty
> "descriptions" -- the body of a doc comment, before the block tags.
>
> It is already the case that doclint checks for missing/empty descriptions in
> block tags, like @param, @return, etc.
>
> There are three cases to consider:
>
> * The comment itself is missing: this was already checked and reported as
> "missing comment".
> * The comment is present, but is empty ... this seems relatively unlikely,
> but is nevertheless checked and reported as "empty comment".
> * The comment is present but only has block tags. This is not always a
> problem, since the description may be inherited, for example, in an
> overriding method, but when it is an issue, it is reported as "no initial
> description".
>
> No diagnostic is reported if the description is missing but the first tag is
> `@deprecated`, because in this case, javadoc will use the body of the
> `@deprecated` tag for the summary. See
> [`Character.UnicodeBlock#SURROGATES_AREA`](https://docs.oracle.com/en/java/javase/15/docs/api/java.base/java/lang/Character.UnicodeBlock.html#SURROGATES_AREA)
> and the corresponding entry in the summary table to see an example of this
> situation.
>
> Diagnostics are reported if the declaration is not an overriding method and
> does not begin with `@deprecated`. This occurs in a number of places in the
> `java.desktop` module, often where the doc comment is of the form `/**
> @return _description_ */`. To suppress those warnings for now, the
> `-missing` option is added to `DOCLINT_OPTIONS` for the `java.desktop`
> module. To see the effects of this anti-pattern, look at the empty
> descriptions for
> [`javax.swing.text.html.parser.AttributeList`](https://docs.oracle.com/en/java/javase/15/docs/api/java.desktop/javax/swing/text/html/parser/AttributeList.html#method.summary)
>
> Many of the doclint tests needed to be updated, because of their
> over-simplistic minimal comments. It was not possible, in general, to avoid
> updating the source code while preserving line numbers, so in many cases, the
> golden `*.out` files had to be updated as well.
>
> A new test is added, focussing on the different forms of empty/missing
> descriptions, as described above.
Looks good. One thing I wonder about is why you only look for `@deprecated` in
the first block tag. I guess it is just a convention to add this tag at the
first position?
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line
203:
> 201: // Don't report an empty description if the comment
> begins with @deprecated,
> 202: // because javadoc will use the content of that tag
> in summary tables.
> 203: if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
Why do we only check the first block tag here?
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclint/Checker.java line
204:
> 202: // because javadoc will use the content of that tag
> in summary tables.
> 203: if (firstTag.getKind() != DocTree.Kind.DEPRECATED) {
> 204: env.messages.report(MISSING, Kind.WARNING, tree,
> "dc.empty.description");
Is there a reason to not use `reportMissing` here?
-
Marked as reviewed by hannesw (Reviewer).
PR: https://git.openjdk.java.net/jdk/pull/5106
Integrated: JDK-8263468: New page for "recent" new API
On Wed, 26 May 2021 16:02:29 GMT, Hannes Wallnöfer wrote: > This adds a new kind of summary list for new API added in specific releases, > and adds information to the deprecated API list about elements that were > deprecated in the given releases. > > The changes to the code are relatively minor thanks to the existing > infrastructure for summary list pages, which was extended by adding the > `getTableCaption` and `addTableTabs` methods to `SummaryListWriter.java` in > order to generate tabbed tables. > > One important area that needs to be reviewed is the addition of resources in > `standard.properties`. A relatively big share of discussion and effort went > into shaping the UI messages. > > The build system change adds options to generate API changes for all releases > after JDK 11, with "New API since JDK 11" as page title for the new API page. > I uploaded the generated documentation here: > > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/new-list.html > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/deprecated-list.html This pull request has now been integrated. Changeset: dc6c96bb Author:Hannes Wallnöfer URL: https://git.openjdk.java.net/jdk/commit/dc6c96bbaf1c0af3eacaa2e59646ed7c5bb0767d Stats: 1920 lines in 40 files changed: 1846 ins; 34 del; 40 mod 8263468: New page for "recent" new API Reviewed-by: erikj, jjg - PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API [v2]
On Mon, 7 Jun 2021 14:53:55 GMT, Jonathan Gibbons wrote:
>> Hannes Wallnöfer has updated the pull request incrementally with one
>> additional commit since the last revision:
>>
>> JDK-8263468: automate build integration
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties
> line 268:
>
>> 266: doclet.help.new.body=\
>> 267: The {0} page lists APIs that have been added in recent releases. \
>> 268: The content of this page is based on information provided by
>> Javadoc @since tags.
>
> Either change to "JavaDoc" or (preferably?) just delete this word, or even
> the sentence.
>
> Is there any interaction with `-nosince`? Should there be?
I removed the second sentence.
There is no interaction with `-nosince`. I one point I thought `-nosince`
should disable this feature, but actually both features are just different ways
of displaying the information stored in `@since` tags that don't depend on each
other.
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Extern.java
> line 337:
>
>> 335: */
>> 336: public int getSourceVersionNumber() {
>> 337: return configuration.docEnv.getSourceVersion().ordinal();
>
> As a general comment, I believe Joe does not encourage use of `ordinal`
I undid this change as it's not really part of the feature.
-
PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API [v3]
On Mon, 7 Jun 2021 15:27:21 GMT, Jonathan Gibbons wrote: >> Hannes Wallnöfer has updated the pull request with a new target base due to >> a merge or a rebase. The pull request now contains 16 commits: >> >> - Merge branch 'master' into JDK-8263468 >> - JDK-8263468: automate build integration >> - JDK-8263468: make constant static >> - JDK-8263468: Remove unused DocPaths methods >> - JDK-8263468: Cleanup >> - JDK-8263468: Add tests >> - JDK-8263468: Update to new Table methods >> - Merge branch 'master' into JDK-8263468 >> >># Conflicts: >># >> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css >> - JDK-8263468: Fix tests >> - JDK-8263468: Update to latest CSR >> - ... and 6 more: >> https://git.openjdk.java.net/jdk/compare/3396b69f...3b13ae32 > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/NewAPIListWriter.java > line 49: > >> 47: /** >> 48: * Generate File to list all the new API elements with the >> 49: * appropriate links. > > (minor) not standard form of comment, but it's "only" an internal class, so > could be fixed up later This comment and the comment below was copied and adapter from another SummaryListWriter subclass. I took the liberty of rewriting both comments. - PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API [v2]
On Mon, 7 Jun 2021 14:52:57 GMT, Jonathan Gibbons wrote: >> Hannes Wallnöfer has updated the pull request incrementally with one >> additional commit since the last revision: >> >> JDK-8263468: automate build integration > > src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/standard.properties > line 112: > >> 110: doclet.Deprecated_Tabs_Intro=(The leftmost tab "Deprecated ..." >> indicates all the \ >> 111: deprecated elements, regardless of the releases in which they were >> deprecated. \ >> 112: Each of the righthand tabs "Deprecated in ..." indicates the >> elements deprecated \ > > "Each of the righthand" doesn't read well. Would "Each of the other" be > better? Changed to "Each of the other". - PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API [v4]
> This adds a new kind of summary list for new API added in specific releases, > and adds information to the deprecated API list about elements that were > deprecated in the given releases. > > The changes to the code are relatively minor thanks to the existing > infrastructure for summary list pages, which was extended by adding the > `getTableCaption` and `addTableTabs` methods to `SummaryListWriter.java` in > order to generate tabbed tables. > > One important area that needs to be reviewed is the addition of resources in > `standard.properties`. A relatively big share of discussion and effort went > into shaping the UI messages. > > The build system change adds options to generate API changes for all releases > after JDK 11, with "New API since JDK 11" as page title for the new API page. > I uploaded the generated documentation here: > > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/new-list.html > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/deprecated-list.html Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision: JDK-8263468: review comments - Changes: - all: https://git.openjdk.java.net/jdk/pull/4209/files - new: https://git.openjdk.java.net/jdk/pull/4209/files/3b13ae32..c9c5f832 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=4209=03 - incr: https://webrevs.openjdk.java.net/?repo=jdk=4209=02-03 Stats: 29 lines in 7 files changed: 6 ins; 2 del; 21 mod Patch: https://git.openjdk.java.net/jdk/pull/4209.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/4209/head:pull/4209 PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API [v3]
> This adds a new kind of summary list for new API added in specific releases, > and adds information to the deprecated API list about elements that were > deprecated in the given releases. > > The changes to the code are relatively minor thanks to the existing > infrastructure for summary list pages, which was extended by adding the > `getTableCaption` and `addTableTabs` methods to `SummaryListWriter.java` in > order to generate tabbed tables. > > One important area that needs to be reviewed is the addition of resources in > `standard.properties`. A relatively big share of discussion and effort went > into shaping the UI messages. > > The build system change adds options to generate API changes for all releases > after JDK 11, with "New API since JDK 11" as page title for the new API page. > I uploaded the generated documentation here: > > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/new-list.html > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/deprecated-list.html Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 16 commits: - Merge branch 'master' into JDK-8263468 - JDK-8263468: automate build integration - JDK-8263468: make constant static - JDK-8263468: Remove unused DocPaths methods - JDK-8263468: Cleanup - JDK-8263468: Add tests - JDK-8263468: Update to new Table methods - Merge branch 'master' into JDK-8263468 # Conflicts: # src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/resources/stylesheet.css - JDK-8263468: Fix tests - JDK-8263468: Update to latest CSR - ... and 6 more: https://git.openjdk.java.net/jdk/compare/3396b69f...3b13ae32 - Changes: https://git.openjdk.java.net/jdk/pull/4209/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk=4209=02 Stats: 1925 lines in 41 files changed: 1846 ins; 38 del; 41 mod Patch: https://git.openjdk.java.net/jdk/pull/4209.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/4209/head:pull/4209 PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API [v2]
On Thu, 27 May 2021 13:32:36 GMT, Erik Joelsson wrote: >> Yes, there are a few things, but in the build itself, we are down to a >> single config file today, so I would really appreciate if this could be >> figured out. I can provide the implementation for generating this, but I >> need to understand what the expected pattern is. From what I can see, it >> looks like $(sequence N, M) where N is the last LTS+1 and M is current JDK >> version. Then the string has "JDK N" in it. M is already well defined, so >> the only new input here is N, which we could move to the version numbers >> config file (make/conf/version-numbers.conf). Something like >> DEFAULT_VERSION_DOCS_API_SINCE=11. There is some additional boilerplate >> needed, and the sequence macro of course, but does this sound reasonable to >> you? > > We actually have a sequence macro already, so generating the list can be done > like this: > > $(call CommaList,$(call sequence 12, 17)) > > Or if what you have is 11 and 17: > > $(call CommaList, $(filter-out 11, $(call sequence 11, 17))) Thanks for the help and for providing all the pieces, Erik! I just added a new commit and I think I got everything working. - PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API [v2]
> This adds a new kind of summary list for new API added in specific releases, > and adds information to the deprecated API list about elements that were > deprecated in the given releases. > > The changes to the code are relatively minor thanks to the existing > infrastructure for summary list pages, which was extended by adding the > `getTableCaption` and `addTableTabs` methods to `SummaryListWriter.java` in > order to generate tabbed tables. > > One important area that needs to be reviewed is the addition of resources in > `standard.properties`. A relatively big share of discussion and effort went > into shaping the UI messages. > > The build system change adds options to generate API changes for all releases > after JDK 11, with "New API since JDK 11" as page title for the new API page. > I uploaded the generated documentation here: > > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/new-list.html > http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/deprecated-list.html Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision: JDK-8263468: automate build integration - Changes: - all: https://git.openjdk.java.net/jdk/pull/4209/files - new: https://git.openjdk.java.net/jdk/pull/4209/files/e81532b2..2a9dbbbf Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=4209=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk=4209=00-01 Stats: 10 lines in 4 files changed: 9 ins; 0 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/4209.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/4209/head:pull/4209 PR: https://git.openjdk.java.net/jdk/pull/4209
Re: RFR: JDK-8263468: New page for "recent" new API
On Thu, 27 May 2021 12:52:34 GMT, Erik Joelsson wrote: >> This adds a new kind of summary list for new API added in specific releases, >> and adds information to the deprecated API list about elements that were >> deprecated in the given releases. >> >> The changes to the code are relatively minor thanks to the existing >> infrastructure for summary list pages, which was extended by adding the >> `getTableCaption` and `addTableTabs` methods to `SummaryListWriter.java` in >> order to generate tabbed tables. >> >> One important area that needs to be reviewed is the addition of resources in >> `standard.properties`. A relatively big share of discussion and effort went >> into shaping the UI messages. >> >> The build system change adds options to generate API changes for all >> releases after JDK 11, with "New API since JDK 11" as page title for the new >> API page. I uploaded the generated documentation here: >> >> http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/new-list.html >> http://cr.openjdk.java.net/~hannesw/8263468/api-pr.00/deprecated-list.html > > make/Docs.gmk line 336: > >> 334: >> 335: # Add summary pages for new/deprecated APIs in recent releases >> 336: $1_OPTIONS += --since 12,13,14,15,16,17 --since-label "New API since >> JDK 11" > > How do you expect this to change as the JDK version is bumped? If there is an > expected pattern, then maybe we should try to generate the list instead, so > we don't need to manually update twice a year. I don't have a solution for this problem. AFAIK there are a few things that have to be "bumped" manually between releases, and this would be yet another. Obviously not a great solution. - PR: https://git.openjdk.java.net/jdk/pull/4209
RFR: JDK-8263468: New page for "recent" new API
This adds a new kind of summary list for new API added in specific releases, and adds information to the deprecated API list about elements that were deprecated in the given releases. The changes to the code are relatively minor thanks to the existing infrastructure for summary list pages, which was extended by adding the `getTableCaption` and `addTableTabs` methods to `SummaryListWriter.java` in order to generate tabbed tables. One important area that needs to be reviewed is the addition of resources in `standard.properties`. A relatively big share of discussion and effort went into shaping the UI messages. The build system change adds options to generate API changes for all releases after JDK 11, with "New API since JDK 11" as page title for the new API page. - Commit messages: - JDK-8263468: make constant static - JDK-8263468: Remove unused DocPaths methods - JDK-8263468: Cleanup - JDK-8263468: Add tests - JDK-8263468: Update to new Table methods - Merge branch 'master' into JDK-8263468 - JDK-8263468: Fix tests - JDK-8263468: Update to latest CSR - JDK-8263468: Tweak help message wording - JDK-8263468: Rename -since to --since, add --since-name option - ... and 4 more: https://git.openjdk.java.net/jdk/compare/9eaa4afc...e81532b2 Changes: https://git.openjdk.java.net/jdk/pull/4209/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk=4209=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8263468 Stats: 1921 lines in 38 files changed: 1842 ins; 38 del; 41 mod Patch: https://git.openjdk.java.net/jdk/pull/4209.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/4209/head:pull/4209 PR: https://git.openjdk.java.net/jdk/pull/4209
Re: [jdk16] RFR: JDK-8247994: Localize javadoc search [v4]
On Thu, 17 Dec 2020 17:10:10 GMT, Jonathan Gibbons wrote: >> This is for JDK16, as a precursor to fixing JDK-8258002. >> >> While it is good to be using localized strings in the generated output, the >> significance for JDK-8258002 is that the strings are now obtained from a >> resource file, and not hardcoded in JavaScript file itself. >> >> The source file `search.js` is renamed to `search.js.template`, and (unlike >> other template files) is copied as-is into the generated image. The values >> in the template are resolved when javadoc is executed, depending on the >> locale in use at the time. Because of the change in the file's extension, >> two makefiles are updated to accommodate the new extension: one is for the >> "interim" javadoc used to generate the API docs; the other is for the >> primary javadoc in the main JDK image. > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Address review comment Marked as reviewed by hannesw (Reviewer). - PR: https://git.openjdk.java.net/jdk16/pull/16
Re: [jdk16] RFR: JDK-8247994: Localize javadoc search [v3]
On Thu, 17 Dec 2020 16:39:17 GMT, Jonathan Gibbons wrote: >> This is for JDK16, as a precursor to fixing JDK-8258002. >> >> While it is good to be using localized strings in the generated output, the >> significance for JDK-8258002 is that the strings are now obtained from a >> resource file, and not hardcoded in JavaScript file itself. >> >> The source file `search.js` is renamed to `search.js.template`, and (unlike >> other template files) is copied as-is into the generated image. The values >> in the template are resolved when javadoc is executed, depending on the >> locale in use at the time. Because of the change in the file's extension, >> two makefiles are updated to accommodate the new extension: one is for the >> "interim" javadoc used to generate the API docs; the other is for the >> primary javadoc in the main JDK image. > > Jonathan Gibbons has updated the pull request incrementally with one > additional commit since the last revision: > > Address review comment src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search.js.template line 40: > 38: var MIN_RESULTS = 3; > 39: var MAX_RESULTS = 500; > 40: var UNNAMED = ">"; Oops, an additional closing angle bracket slipped there. - PR: https://git.openjdk.java.net/jdk16/pull/16
Re: [jdk16] RFR: JDK-8247994: Localize javadoc search
On Mon, 14 Dec 2020 09:34:31 GMT, Hannes Wallnöfer wrote:
>> This is for JDK16, as a precursor to fixing JDK-8258002.
>>
>> While it is good to be using localized strings in the generated output, the
>> significance for JDK-8258002 is that the strings are now obtained from a
>> resource file, and not hardcoded in JavaScript file itself.
>>
>> The source file `search.js` is renamed to `search.js.template`, and (unlike
>> other template files) is copied as-is into the generated image. The values
>> in the template are resolved when javadoc is executed, depending on the
>> locale in use at the time. Because of the change in the file's extension,
>> two makefiles are updated to accommodate the new extension: one is for the
>> "interim" javadoc used to generate the API docs; the other is for the
>> primary javadoc in the main JDK image.
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFile.java
> line 256:
>
>> 254: sb.append(resources.getText(m.group("key")));
>> 255: } catch (MissingResourceException e) {
>> 256: sb.append(m.group());
>
> Shouldn't we propagate an error here, or issue a warning? If a key is missing
> localized properties the value from default properties should be used, so
> this should never happen, right?
I see the added check for "##REPLACE:" in TestSearch.java will catch that case,
so I guess it's ok.
-
PR: https://git.openjdk.java.net/jdk16/pull/16
Re: [jdk16] RFR: JDK-8247994: Localize javadoc search
On Sun, 13 Dec 2020 00:19:59 GMT, Jonathan Gibbons wrote:
> This is for JDK16, as a precursor to fixing JDK-8258002.
>
> While it is good to be using localized strings in the generated output, the
> significance for JDK-8258002 is that the strings are now obtained from a
> resource file, and not hardcoded in JavaScript file itself.
>
> The source file `search.js` is renamed to `search.js.template`, and (unlike
> other template files) is copied as-is into the generated image. The values in
> the template are resolved when javadoc is executed, depending on the locale
> in use at the time. Because of the change in the file's extension, two
> makefiles are updated to accommodate the new extension: one is for the
> "interim" javadoc used to generate the API docs; the other is for the primary
> javadoc in the main JDK image.
Looks good in general. `` shouldn't be localized as it is an internal
tag (see inline comment).
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/resources/search.js.template
line 40:
> 38: var MIN_RESULTS = 3;
> 39: var MAX_RESULTS = 500;
> 40: var UNNAMED = "##REPLACE:doclet.search.unnamed##";
`` is not a string that is ever shown to the user, it is what is used
by javadoc to denote the default package (see
`toolkit.util.DocletConstants.DEFAULT_PACKAGE_NAME`). This variable shouldn't
be localized as that would break behaviour for code in the default package (and
show the localized string as package name, instead of no package name).
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/DocFile.java
line 256:
> 254: sb.append(resources.getText(m.group("key")));
> 255: } catch (MissingResourceException e) {
> 256: sb.append(m.group());
Shouldn't we propagate an error here, or issue a warning? If a key is missing
localized properties the value from default properties should be used, so this
should never happen, right?
-
Changes requested by hannesw (Reviewer).
PR: https://git.openjdk.java.net/jdk16/pull/16
Re: RFR: JDK-6251738: Want a top-level summary page that itemizes all spec documents referenced from javadocs (OEM spec)
On Thu, 22 Oct 2020 02:40:44 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.
It's very instructive to see a new tag introduced from scratch with all the
accompanying infrastructure and tests. The changes looks good to me, but I need
to stress than I'm not an expert on some of the affected areas such as the
jdk.compiler parts.
-
Marked as reviewed by hannesw (Reviewer).
PR: https://git.openjdk.java.net/jdk/pull/790
Re: RFR: JDK-8250768: javac should be adapted to changes in JEP 12 [v2]
On Tue, 20 Oct 2020 12:15:23 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 with a new target base due to a merge
> or a rebase. The pull request now contains 35 commits:
>
> - Merge branch 'JDK-8250768-dev' of https://github.com/lahodaj/jdk into
> JDK-8250768
> - More fixing tests.
> - Fixing tests.
> - Using unique sections for preview warning sections, as suggested.
> - Merge branch 'master' into JDK-8250768
> - Reflecting review comments.
> - Fixing tests.
> - Various cleanup.
> - The Preview taglet is not needed anymore.
> - There is not jdk.internal package anymore
> - ... and 25 more:
> https://git.openjdk.java.net/jdk/compare/98ec4a67...be1d8651
The javadoc code changes look reasonable, and the preview bits in the generated
documentation look good as well.
Apart from my inline comments which all address minor issues, there are a few
things I don't like around `PreviewListWriter`: its code replication with
`DeprecatedListWriter, and it adds things to HtmlDocletWriter and HtmlStyle
that I don't think are strictly necessary. However, I wouldn't expect you to
know how we like things done in javadoc, so maybe the simplest solution would
be for one of us to go over the javadoc bits, either as part of this pull
request or (if you prefer to get it integrated rather sooner) as a follow-up
task.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/toolkit/util/Utils.java
line 3164:
> 3162: }
> 3163:
> 3164: public Set elementFlags(Element el) {
It seems like the sole use of this method and the `ElementFlag` enum below is
to determine whether a preview warning note should be generated for an element.
Is there something that speaks against simplifying it to reflect that purpose,
e.g. change its name to `hasPreviewNote` or `hasPreviewContent` and change the
return type to `boolean`? Of course that's unless you foresee adding more
`ElementFlag` values in the future.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
line 125:
> 123: import static javax.lang.model.element.ElementKind.METHOD;
> 124: import static javax.lang.model.element.ElementKind.PACKAGE;
> 125: import jdk.javadoc.internal.doclets.formats.html.markup.RawHtml;
These imports as well as HtmlAttr above aren't used.
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/LinkInfoImpl.java
line 247:
> 245: * The member this link points to (if any).
> 246: */
> 247: public Element whereMember;
I don't think `whereMember` is a great name (and `where` above is not a great
name either). What about naming this `targetMember`
Re: RFR: JDK-8250768: javac should be adapted to changes in JEP 12
On Mon, 19 Oct 2020 14:09:51 GMT, Hannes Wallnöfer 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
>
> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
> line 2238:
>
>> 2236: if (previewTree != null) {
>> 2237: previewDiv.add(new
>> HtmlTree(TagName.A).put(HtmlAttr.ID, "preview")
>> 2238: .add(new
>> RawHtml(utils.getPreviewTreeSummaryOrDetails(previewTree, false;
>
> The `id` attribute needs to be unique within the page, so in addition to make
> the value not a valid java identifier (as
> @jonathan-gibbons pointed out in a comment elsewhere) we need to support
> multiple preview ids per page. One way to do
> this would be to add the element name to the id value, e.g. `preview- name>`.
Of course the element name won't do for overloaded methods and constructors...
`Links#getAnchor(ExecutableElement)`
should be used for those.
-
PR: https://git.openjdk.java.net/jdk/pull/703
Re: RFR: JDK-8250768: javac should be adapted to changes in JEP 12
On Fri, 16 Oct 2020 15:20:03 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
src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/HtmlDocletWriter.java
line 2238:
> 2236: if (previewTree != null) {
> 2237: previewDiv.add(new HtmlTree(TagName.A).put(HtmlAttr.ID,
> "preview")
> 2238: .add(new
> RawHtml(utils.getPreviewTreeSummaryOrDetails(previewTree, false;
The `id` attribute needs to be unique within the page, so in addition to make
the value not a valid java identifier (as
@jonathan-gibbons pointed out in a comment elsewhere) we need to support
multiple preview ids per page. One way to do
this would be to add the element name to the id value, e.g. `preview-`.
-
PR: https://git.openjdk.java.net/jdk/pull/703
Integrated: 8216497: javadoc should auto-link to platform classes
On Tue, 15 Sep 2020 09:10:54 GMT, Hannes Wallnöfer wrote: > This pull request is identical with the RFR previously sent for the Mercurial > repository: > > https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html > > I'm copy-pasting the comments from the original RFR below. > > Most of the new code is added to the Extern class where it fits in quite > nicely and can use the existing supporting > code for setting up external links. > The default behaviour is to generate links to docs.oracle.com for released > versions and download.java.net for > prereleases. Platform documentation URLs can be configured using the new > --link-platform-properties option to > provide a properties file with URLs pointing to to alternative locations. See > the CSR linked above for more details on > the new options. The feature can be disabled using the --no-platform-link > option, generating the same output as > previously. One problem I had to solve was how to handle the transition > from prerelease versions to final releases, > since the location of the documentation changes in this transition. For > obvious reasons we don’t want to make that > switch via code change at a time shortly before release. The way it is done > is that we determine if the current > javadoc instance is a prerelease version as indicated by the Version returned > by BaseConfiguration#getDocletVersion(), > and then check whether the release/source version of the current javadoc > execution uses the same (latest) version. This > means that that only the latest version will ever generate prerelease links > (e.g. running current javadoc 16 with > source version 15 will generate links to the final release documentation) but > I think this is acceptable. Another > issue I spent some time getting right was tests. New releases require a new > element-list resource*), so tests have to > pick up new releases. On the other hand, we don’t want hundreds of tests to > fail when a new release is added, ideally > there should be one test with a clear message. Because of this, when a > release is encountered for which no > element-list is available a warning is generated instead of an error, and the > documentation is generated without > platform links as if running with --no-platform-link option. This allows most > existing tests to pass and just the new > test to fail with a relatively clear message of what is wrong. > *) I also thought about generating the element-list for the current release > at build time. It’s quite involved, and we > still need to maintain element-lists for older versions, so I’m not sure > it’s worth it. > > For existing tests that check output affected by the new option I added the > --no-platform-link option to disable the > feature. Otherwise we’d have to update those tests with each new release (or > else freeze the tests to use some static > release or source version, which we don’t want either). I updated the CSR to > the new code. It also needs to be > reviewed: https://bugs.openjdk.java.net/browse/JDK-8251181 > > Thanks, > Hannes This pull request has now been integrated. Changeset: 1e8e543b Author:Hannes Wallnöfer URL: https://git.openjdk.java.net/jdk/commit/1e8e543b Stats: 1844 lines in 51 files changed: 1831 ins; 4 del; 9 mod 8216497: javadoc should auto-link to platform classes Co-authored-by: Jan Lahoda Reviewed-by: erikj, jjg - PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes [v4]
> This pull request is identical with the RFR previously sent for the Mercurial > repository: > > https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html > > I'm copy-pasting the comments from the original RFR below. > > Most of the new code is added to the Extern class where it fits in quite > nicely and can use the existing supporting > code for setting up external links. > The default behaviour is to generate links to docs.oracle.com for released > versions and download.java.net for > prereleases. Platform documentation URLs can be configured using the new > --link-platform-properties option to > provide a properties file with URLs pointing to to alternative locations. See > the CSR linked above for more details on > the new options. The feature can be disabled using the --no-platform-link > option, generating the same output as > previously. One problem I had to solve was how to handle the transition > from prerelease versions to final releases, > since the location of the documentation changes in this transition. For > obvious reasons we don’t want to make that > switch via code change at a time shortly before release. The way it is done > is that we determine if the current > javadoc instance is a prerelease version as indicated by the Version returned > by BaseConfiguration#getDocletVersion(), > and then check whether the release/source version of the current javadoc > execution uses the same (latest) version. This > means that that only the latest version will ever generate prerelease links > (e.g. running current javadoc 16 with > source version 15 will generate links to the final release documentation) but > I think this is acceptable. Another > issue I spent some time getting right was tests. New releases require a new > element-list resource*), so tests have to > pick up new releases. On the other hand, we don’t want hundreds of tests to > fail when a new release is added, ideally > there should be one test with a clear message. Because of this, when a > release is encountered for which no > element-list is available a warning is generated instead of an error, and the > documentation is generated without > platform links as if running with --no-platform-link option. This allows most > existing tests to pass and just the new > test to fail with a relatively clear message of what is wrong. > *) I also thought about generating the element-list for the current release > at build time. It’s quite involved, and we > still need to maintain element-lists for older versions, so I’m not sure > it’s worth it. > > For existing tests that check output affected by the new option I added the > --no-platform-link option to disable the > feature. Otherwise we’d have to update those tests with each new release (or > else freeze the tests to use some static > release or source version, which we don’t want either). I updated the CSR to > the new code. It also needs to be > reviewed: https://bugs.openjdk.java.net/browse/JDK-8251181 > > Thanks, > Hannes Hannes Wallnöfer has updated the pull request with a new target base due to a merge or a rebase. The incremental webrev excludes the unrelated changes brought in by the merge/rebase. The pull request contains seven additional commits since the last revision: - Fix test failure - Merge branch 'master' into JDK-8216497 - Rename --no-platform-link option plus minor cleanup - Merge pull request #1 from lahodaj/JDK-8216497 Automatically generate the elements-list data from the ct.sym for releases 11+, including the current release under development - Generating current release list for javadoc; using hardcoded lists for versions < 11 - Attempting to (mostly) generate the javadoc release manifests from ct.sym historical data. - 8216497: javadoc should auto-link to platform classes - Changes: - all: https://git.openjdk.java.net/jdk/pull/171/files - new: https://git.openjdk.java.net/jdk/pull/171/files/6009dd70..991daef5 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=171=03 - incr: https://webrevs.openjdk.java.net/?repo=jdk=171=02-03 Stats: 69874 lines in 2995 files changed: 23958 ins; 34697 del; 11219 mod Patch: https://git.openjdk.java.net/jdk/pull/171.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/171/head:pull/171 PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes [v3]
> This pull request is identical with the RFR previously sent for the Mercurial > repository: > > https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html > > I'm copy-pasting the comments from the original RFR below. > > Most of the new code is added to the Extern class where it fits in quite > nicely and can use the existing supporting > code for setting up external links. > The default behaviour is to generate links to docs.oracle.com for released > versions and download.java.net for > prereleases. Platform documentation URLs can be configured using the new > --link-platform-properties option to > provide a properties file with URLs pointing to to alternative locations. See > the CSR linked above for more details on > the new options. The feature can be disabled using the --no-platform-link > option, generating the same output as > previously. One problem I had to solve was how to handle the transition > from prerelease versions to final releases, > since the location of the documentation changes in this transition. For > obvious reasons we don’t want to make that > switch via code change at a time shortly before release. The way it is done > is that we determine if the current > javadoc instance is a prerelease version as indicated by the Version returned > by BaseConfiguration#getDocletVersion(), > and then check whether the release/source version of the current javadoc > execution uses the same (latest) version. This > means that that only the latest version will ever generate prerelease links > (e.g. running current javadoc 16 with > source version 15 will generate links to the final release documentation) but > I think this is acceptable. Another > issue I spent some time getting right was tests. New releases require a new > element-list resource*), so tests have to > pick up new releases. On the other hand, we don’t want hundreds of tests to > fail when a new release is added, ideally > there should be one test with a clear message. Because of this, when a > release is encountered for which no > element-list is available a warning is generated instead of an error, and the > documentation is generated without > platform links as if running with --no-platform-link option. This allows most > existing tests to pass and just the new > test to fail with a relatively clear message of what is wrong. > *) I also thought about generating the element-list for the current release > at build time. It’s quite involved, and we > still need to maintain element-lists for older versions, so I’m not sure > it’s worth it. > > For existing tests that check output affected by the new option I added the > --no-platform-link option to disable the > feature. Otherwise we’d have to update those tests with each new release (or > else freeze the tests to use some static > release or source version, which we don’t want either). I updated the CSR to > the new code. It also needs to be > reviewed: https://bugs.openjdk.java.net/browse/JDK-8251181 > > Thanks, > Hannes Hannes Wallnöfer has updated the pull request incrementally with one additional commit since the last revision: Rename --no-platform-link option plus minor cleanup - Changes: - all: https://git.openjdk.java.net/jdk/pull/171/files - new: https://git.openjdk.java.net/jdk/pull/171/files/6d659ae3..6009dd70 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=171=02 - incr: https://webrevs.openjdk.java.net/?repo=jdk=171=01-02 Stats: 73 lines in 38 files changed: 0 ins; 0 del; 73 mod Patch: https://git.openjdk.java.net/jdk/pull/171.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/171/head:pull/171 PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes [v2]
On Tue, 22 Sep 2020 17:30:19 GMT, Jonathan Gibbons wrote:
>> Hannes Wallnöfer has updated the pull request incrementally with three
>> additional commits since the last revision:
>>
>> - Merge pull request #1 from lahodaj/JDK-8216497
>>
>>Automatically generate the elements-list data from the ct.sym for
>> releases 11+, including the current release under
>>development
>> - Generating current release list for javadoc; using hardcoded lists for
>> versions < 11
>> - Attempting to (mostly) generate the javadoc release manifests from ct.sym
>> historical data.
>
> test/langtools/jdk/javadoc/doclet/testAnnotationTypes/TestAnnotationTypes.java
> line 49:
>
>> 47: javadoc("-d", "out-1",
>> 48: "-sourcepath", testSrc,
>> 49: "--no-platform-link",
>
> I see lots of instances of `no-platform-link` in this and subsequent tests.
> `JavadocTester` does have the concept of
> default options, although that may be more for the behavior after executing
> javadoc and not for the options given to
> javadoc itself. Is it worth supporting default javadoc options, since that
> the default can be disabled for specific
> tests?
I can't really find how `JavadocTester` uses or supports default options. My
concern with this would be that it would
make JavadocTester less transparent and intuitive to use, as you'd have to be
aware what the default options are.
-
PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes [v2]
> This pull request is identical with the RFR previously sent for the Mercurial > repository: > > https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html > > I'm copy-pasting the comments from the original RFR below. > > Most of the new code is added to the Extern class where it fits in quite > nicely and can use the existing supporting > code for setting up external links. > The default behaviour is to generate links to docs.oracle.com for released > versions and download.java.net for > prereleases. Platform documentation URLs can be configured using the new > --link-platform-properties option to > provide a properties file with URLs pointing to to alternative locations. See > the CSR linked above for more details on > the new options. The feature can be disabled using the --no-platform-link > option, generating the same output as > previously. One problem I had to solve was how to handle the transition > from prerelease versions to final releases, > since the location of the documentation changes in this transition. For > obvious reasons we don’t want to make that > switch via code change at a time shortly before release. The way it is done > is that we determine if the current > javadoc instance is a prerelease version as indicated by the Version returned > by BaseConfiguration#getDocletVersion(), > and then check whether the release/source version of the current javadoc > execution uses the same (latest) version. This > means that that only the latest version will ever generate prerelease links > (e.g. running current javadoc 16 with > source version 15 will generate links to the final release documentation) but > I think this is acceptable. Another > issue I spent some time getting right was tests. New releases require a new > element-list resource*), so tests have to > pick up new releases. On the other hand, we don’t want hundreds of tests to > fail when a new release is added, ideally > there should be one test with a clear message. Because of this, when a > release is encountered for which no > element-list is available a warning is generated instead of an error, and the > documentation is generated without > platform links as if running with --no-platform-link option. This allows most > existing tests to pass and just the new > test to fail with a relatively clear message of what is wrong. > *) I also thought about generating the element-list for the current release > at build time. It’s quite involved, and we > still need to maintain element-lists for older versions, so I’m not sure > it’s worth it. > > For existing tests that check output affected by the new option I added the > --no-platform-link option to disable the > feature. Otherwise we’d have to update those tests with each new release (or > else freeze the tests to use some static > release or source version, which we don’t want either). I updated the CSR to > the new code. It also needs to be > reviewed: https://bugs.openjdk.java.net/browse/JDK-8251181 > > Thanks, > Hannes Hannes Wallnöfer has updated the pull request incrementally with three additional commits since the last revision: - Merge pull request #1 from lahodaj/JDK-8216497 Automatically generate the elements-list data from the ct.sym for releases 11+, including the current release under development - Generating current release list for javadoc; using hardcoded lists for versions < 11 - Attempting to (mostly) generate the javadoc release manifests from ct.sym historical data. - Changes: - all: https://git.openjdk.java.net/jdk/pull/171/files - new: https://git.openjdk.java.net/jdk/pull/171/files/2aed84f8..6d659ae3 Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jdk=171=01 - incr: https://webrevs.openjdk.java.net/?repo=jdk=171=00-01 Stats: 2007 lines in 9 files changed: 308 ins; 1698 del; 1 mod Patch: https://git.openjdk.java.net/jdk/pull/171.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/171/head:pull/171 PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes
On Tue, 15 Sep 2020 12:56:13 GMT, Erik Joelsson wrote: >> This pull request is identical with the RFR previously sent for the >> Mercurial repository: >> >> https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html >> >> I'm copy-pasting the comments from the original RFR below. >> >> Most of the new code is added to the Extern class where it fits in quite >> nicely and can use the existing supporting >> code for setting up external links. >> The default behaviour is to generate links to docs.oracle.com for released >> versions and download.java.net for >> prereleases. Platform documentation URLs can be configured using the new >> --link-platform-properties option to >> provide a properties file with URLs pointing to to alternative locations. >> See the CSR linked above for more details on >> the new options. The feature can be disabled using the --no-platform-link >> option, generating the same output as >> previously. One problem I had to solve was how to handle the transition >> from prerelease versions to final releases, >> since the location of the documentation changes in this transition. For >> obvious reasons we don’t want to make that >> switch via code change at a time shortly before release. The way it is done >> is that we determine if the current >> javadoc instance is a prerelease version as indicated by the Version >> returned by BaseConfiguration#getDocletVersion(), >> and then check whether the release/source version of the current javadoc >> execution uses the same (latest) version. This >> means that that only the latest version will ever generate prerelease links >> (e.g. running current javadoc 16 with >> source version 15 will generate links to the final release documentation) >> but I think this is acceptable. Another >> issue I spent some time getting right was tests. New releases require a new >> element-list resource*), so tests have to >> pick up new releases. On the other hand, we don’t want hundreds of tests to >> fail when a new release is added, ideally >> there should be one test with a clear message. Because of this, when a >> release is encountered for which no >> element-list is available a warning is generated instead of an error, and >> the documentation is generated without >> platform links as if running with --no-platform-link option. This allows >> most existing tests to pass and just the new >> test to fail with a relatively clear message of what is wrong. >> *) I also thought about generating the element-list for the current release >> at build time. It’s quite involved, and we >> still need to maintain element-lists for older versions, so I’m not sure >> it’s worth it. >> >> For existing tests that check output affected by the new option I added the >> --no-platform-link option to disable the >> feature. Otherwise we’d have to update those tests with each new release (or >> else freeze the tests to use some static >> release or source version, which we don’t want either). I updated the CSR >> to the new code. It also needs to be >> reviewed: https://bugs.openjdk.java.net/browse/JDK-8251181 >> >> Thanks, >> Hannes > > Build changes look good. Converted to draft as @lahodaj has offered to enhance the feature as described in the comments above. - PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR: 8216497: javadoc should auto-link to platform classes
On Tue, 15 Sep 2020 11:30:09 GMT, Jan Lahoda wrote:
>> This pull request is identical with the RFR previously sent for the
>> Mercurial repository:
>>
>> https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html
>>
>> I'm copy-pasting the comments from the original RFR below.
>>
>> Most of the new code is added to the Extern class where it fits in quite
>> nicely and can use the existing supporting
>> code for setting up external links.
>> The default behaviour is to generate links to docs.oracle.com for released
>> versions and download.java.net for
>> prereleases. Platform documentation URLs can be configured using the new
>> --link-platform-properties option to
>> provide a properties file with URLs pointing to to alternative locations.
>> See the CSR linked above for more details on
>> the new options. The feature can be disabled using the --no-platform-link
>> option, generating the same output as
>> previously. One problem I had to solve was how to handle the transition
>> from prerelease versions to final releases,
>> since the location of the documentation changes in this transition. For
>> obvious reasons we don’t want to make that
>> switch via code change at a time shortly before release. The way it is done
>> is that we determine if the current
>> javadoc instance is a prerelease version as indicated by the Version
>> returned by BaseConfiguration#getDocletVersion(),
>> and then check whether the release/source version of the current javadoc
>> execution uses the same (latest) version. This
>> means that that only the latest version will ever generate prerelease links
>> (e.g. running current javadoc 16 with
>> source version 15 will generate links to the final release documentation)
>> but I think this is acceptable. Another
>> issue I spent some time getting right was tests. New releases require a new
>> element-list resource*), so tests have to
>> pick up new releases. On the other hand, we don’t want hundreds of tests to
>> fail when a new release is added, ideally
>> there should be one test with a clear message. Because of this, when a
>> release is encountered for which no
>> element-list is available a warning is generated instead of an error, and
>> the documentation is generated without
>> platform links as if running with --no-platform-link option. This allows
>> most existing tests to pass and just the new
>> test to fail with a relatively clear message of what is wrong.
>> *) I also thought about generating the element-list for the current release
>> at build time. It’s quite involved, and we
>> still need to maintain element-lists for older versions, so I’m not sure
>> it’s worth it.
>>
>> For existing tests that check output affected by the new option I added the
>> --no-platform-link option to disable the
>> feature. Otherwise we’d have to update those tests with each new release (or
>> else freeze the tests to use some static
>> release or source version, which we don’t want either). I updated the CSR
>> to the new code. It also needs to be
>> reviewed: https://bugs.openjdk.java.net/browse/JDK-8251181
>>
>> Thanks,
>> Hannes
>
> I think it would be awesome if we could generate (most of) the
> {element,package}-list-VERSION.txt from the ct.sym
> historical data at build time. This would (hopefully) help with long-term
> maintenance. I've started to sketch that
> here:
> https://github.com/lahodaj/jdk/commit/36c1510587a4b050b148eda87ae7a7a89aff9690
> Some comments on the attempt:
> -in this PR, there is package-list-9.txt - should it be element-list-9.txt,
> and should it contain module names (dtto
> element-list-10.txt)?
> -we may (for historical reasons) want to keep the lists for 7, 8, 9 and 10
> (as the historical data in ct.sym do not
> exactly match what is in the package/element lists). It would be better to
> generate everything, but having a fixed list
> for some of the past versions would be better than having to create a new
> list for each new release.
> -the patch does not yet generate the list for the current release, but that
> should be doable.
Thanks for the suggestions and help, Jan!
> I think it would be awesome if we could generate (most of) the
> {element,package}-list-VERSION.txt from the ct.sym
> historical data at build time. This would (hopefully) help with long-term
> maintenance. I've started to sketch that
> here:
> [lahodaj@36c1510](https://github.com/lahodaj/jdk/commit/36c1510587a4b050b148eda87ae7a7a89aff9690)
I agree files should be generated dynamically. I knew about the sym files but
wasn't sure how to go about it. Thanks a
lot for stepping in and helping out, it's very much appreciated!
> Some comments on the attempt:
> -in this PR, there is package-list-9.txt - should it be element-list-9.txt,
> and should it contain module names (dtto
> element-list-10.txt)?
Javadoc in 9 still uses the old package-centric layout (package-list and no
module names in URL paths). It
RFR: 8216497: javadoc should auto-link to platform classes
This pull request is identical with the RFR previously sent for the Mercurial repository: https://mail.openjdk.java.net/pipermail/javadoc-dev/2020-August/001796.html I'm copy-pasting the comments from the original RFR below. Most of the new code is added to the Extern class where it fits in quite nicely and can use the existing supporting code for setting up external links. The default behaviour is to generate links to docs.oracle.com for released versions and download.java.net for prereleases. Platform documentation URLs can be configured using the new --link-platform-properties option to provide a properties file with URLs pointing to to alternative locations. See the CSR linked above for more details on the new options. The feature can be disabled using the --no-platform-link option, generating the same output as previously. One problem I had to solve was how to handle the transition from prerelease versions to final releases, since the location of the documentation changes in this transition. For obvious reasons we don’t want to make that switch via code change at a time shortly before release. The way it is done is that we determine if the current javadoc instance is a prerelease version as indicated by the Version returned by BaseConfiguration#getDocletVersion(), and then check whether the release/source version of the current javadoc execution uses the same (latest) version. This means that that only the latest version will ever generate prerelease links (e.g. running current javadoc 16 with source version 15 will generate links to the final release documentation) but I think this is acceptable. Another issue I spent some time getting right was tests. New releases require a new element-list resource*), so tests have to pick up new releases. On the other hand, we don’t want hundreds of tests to fail when a new release is added, ideally there should be one test with a clear message. Because of this, when a release is encountered for which no element-list is available a warning is generated instead of an error, and the documentation is generated without platform links as if running with --no-platform-link option. This allows most existing tests to pass and just the new test to fail with a relatively clear message of what is wrong. *) I also thought about generating the element-list for the current release at build time. It’s quite involved, and we still need to maintain element-lists for older versions, so I’m not sure it’s worth it. For existing tests that check output affected by the new option I added the --no-platform-link option to disable the feature. Otherwise we’d have to update those tests with each new release (or else freeze the tests to use some static release or source version, which we don’t want either). I updated the CSR to the new code. It also needs to be reviewed: https://bugs.openjdk.java.net/browse/JDK-8251181 Thanks, Hannes - Commit messages: - 8216497: javadoc should auto-link to platform classes Changes: https://git.openjdk.java.net/jdk/pull/171/files Webrev: https://webrevs.openjdk.java.net/?repo=jdk=171=00 Issue: https://bugs.openjdk.java.net/browse/JDK-8216497 Stats: 3230 lines in 53 files changed: 3220 ins; 4 del; 6 mod Patch: https://git.openjdk.java.net/jdk/pull/171.diff Fetch: git fetch https://git.openjdk.java.net/jdk pull/171/head:pull/171 PR: https://git.openjdk.java.net/jdk/pull/171
Re: RFR [15] JDK-8235926: Update @jls @jvms taglets to allow inline usage
Hi Jon, Looks good to me. Hannes > Am 13.12.2019 um 22:21 schrieb Jonathan Gibbons : > > Please review a change to the JDK-specific taglet used to generate links to > the JLS and JVMS specifications. The change is to allow instances of these > tags to be used inline as well as in the series of block tags at the end of a > comment. > > The change leverages the recent fix for javadoc itself, JDK-8235306, which > updates javadoc to allow taglets (in general) to opt-in to bimodal use. > > The generated HTML is either the `...` pair as before, for > block-tag instances, or a simple `...` for the newly-supported > inline instances. It is intentional that the new text for inline instances > does /not/ include any prefix like "See: Java Language Specification", since > that is better handled in the surrounding text. > > This fix does not update any JDK docs to use inline instances; it is just > about permitting them. > > The taglet is the build.tools package. Although it is executed in the > "interim javadoc tool" (i.e. latest sources on boot JDK) it is compiled > against the boot JDK. For this reason, a method which would normally be > marked `@Override` cannot be so marked until JDK 15 is the boot JDK. This > does not affect the use of the tag in the interim javadoc. > > Build tools don't have automated tests. This code was manually tested by > temporarily editing some JDK API to use both the old form and the new form. > The generated file was visually inspected, and also confirmed to have no > warnings or errors reported by the standard `tidy` utility. > > -- Jon > > JBS: https://bugs.openjdk.java.net/browse/JDK-8235926 > Webrev: http://cr.openjdk.java.net/~jjg/8235926/webrev.00/ >
Re: RFR 8204492 Add deprecation annotation to Nashorn APIs and warning to nashorn, jjs
Looks good. Hannes > Am 27.06.2018 um 06:19 schrieb Sundararajan Athijegannathan > : > > Forgot to CC build-dev for makefile changes. > > -Sundar > > On 27/06/18, 9:46 AM, Sundararajan Athijegannathan wrote: >> Please review. >> >> Bug https://bugs.openjdk.java.net/browse/JDK-8204492 >> Webrev http://cr.openjdk.java.net/~sundar/8204492/webrev.01 >> >> Related: >> >> JEP http://openjdk.java.net/jeps/335 >> CSR https://bugs.openjdk.java.net/browse/JDK-8205594 >> >> Thanks, >> -Sundar >>
