Re: RFR: 8344191: Build code should not have classpath exception
On Thu, 14 Nov 2024 12:22:36 GMT, Magnus Ihse Bursie wrote: > In several (most? all?) of the build system files, the copyright header > includes the classpath exception. This makes no sense, and should be removed. > > I have removed the classpath exception from makefiles, autoconf, shell > scripts, properties files, configuration files, IDE support files, build > tools and data. > > The only places where the classpath exception is still kept in the make > directory is as text strings in some build tools, which generate source code > that is bundled with `src.zip`, and thus *must* have the classpath exception. > > This is a huge and autogenerated, but content-wise trivial, PR, and I know > such are hard to review. I recommend looking at the entire diff file instead > of checking this file-by-file in the Github web GUI. (That's bound to be a > painful experience) The policy has long been to use Classpath Exception in the `src` and `make` directories, but not in the `test` directories. If you're changing the policy, you might want to check and update any documentation where the policy might be written down. - PR Comment: https://git.openjdk.org/jdk/pull/22104#issuecomment-2476698524
Re: RFR: 8344056: Use markdown format for man pages
On Wed, 13 Nov 2024 20:17:24 GMT, Kevin Walls wrote: > I think this means the one-true-master copy of a man page is now the public > .md file. All contributors can now change and improve man pages, and would be > expected to make necessary man page updates when making other changes. (Which > is great, I just didn't see it being explicitly said.) Yes, related: Non-trivial updates to these pages should be approved in a CSR, maybe along with any code changes that may make such an update necessary. - PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2474804913
Re: RFR: 8344056: Use markdown format for man pages
On Wed, 13 Nov 2024 17:05:25 GMT, Magnus Ihse Bursie wrote: > Currently, the man pages are stored as troff (a text format) in the open > repo, and a content-wise identical copy is stored as markdown (another text > format) in the closed repo. > > Since markdown is preferred to troff in terms of editing, we make changes to > the man pages in markdown and then convert it to troff. > > This closed-markdown to open-troff processing needs to be done manually by an > Oracle engineer. This is done regularly at the start and end of a new release > cycle, adding to the burden of creating a new release. It is also done (if > any of the reviewers knows about the process) whenever an Oracle engineer > updates a man page. If a community contributor changes the behavior of a > tool, an Oracle engineer needs to change the documentation for them, since > they cannot do it themselves. Without looking in detail at the changes, this is indeed a welcome and long-overdue change! - PR Comment: https://git.openjdk.org/jdk/pull/22081#issuecomment-2474339519
Re: RFR: 8333827: JDK 23 RDP1 L10n resource files update [v2]
On Mon, 10 Jun 2024 21:38:18 GMT, Damon Nguyen wrote: >> While we do not translate Java keywords (when used as such, e.g. "`class` >> not allowed here"), and option names (e.g. `--class-path`) we have typically >> translated other text that is not mandated by the language or tools, (e.g. >> `the name of this class`, ``, ``. >> >> This change seems to be going backwards. >> >> Whatever the policy we use for translating (or not translating) parts of a >> message, we should be consistent across all tools and documents. > > @jonathan-gibbons I just realized that this change to the German file matches > the file with the Japanese and Chinese localized files. By that I mean the > "backwards" translations are also present for the Japanese and Chinese files. > > However, the previous versions of the Japanese and Chinese files don't have > these bits translated. So in summary, I can revert the German file back to > German but the Japanese and Chinese files will still be English for these > parts because I wouldn't know what to revert them to in their local language. > > As a result, I actually think it might be better to change this German file > as shown in the current version of the PR just to remain consistent with the > other localized versions of this file. We can still bring this up to the go > team as an issue, but I think this is the best solution now for this drop at > least. No one else except people reading this PR will spot inconsistencies between translations in different languages. So inconsistencies across languages will not be obvious to end users. But anyone (end-user) using the tool in any one of these languages is likely to spot inconsistencies in the translations for that one language. - PR Review Comment: https://git.openjdk.org/jdk/pull/19609#discussion_r1633937355
Re: RFR: 8333827: JDK 23 RDP1 L10n resource files update
On Fri, 7 Jun 2024 22:46:44 GMT, Damon Nguyen wrote: > This issue is responsible for updating the translations of all the > localize(able) resources in the JDK. Primarily, the changes between JDK 22 > RDP 1 and the integration of the JDK 23 RDP 1 L10n drop will be translated. > > The translation tool adjusted some definitions, which causes some changes in > localized files where the source file had no changes. This causes some words > being reverted from localized languages to English, and some had its > definitions changed. > > Alternatively, the diffs are viewable here and was generated using Jonathan > Gibbons' diff tool for l10n: > https://cr.openjdk.org/~dnguyen/output2/ src/jdk.compiler/share/classes/com/sun/tools/javac/resources/compiler_de.properties line 409: > 407: compiler.err.unconditional.pattern.and.default=Switch umfasst sowohl ein > nicht bedingtes Muster als auch ein Standardlabel > 408: > 409: compiler.err.unconditional.pattern.and.both.boolean.values=Switch > umfasst sowohl boolesche Werte als auch ein nicht bedingtes Muster Here and elsewhere in this file and other translations, I'm surprised `switch` is not being translated, and is being capitalized. In the English form, it is not being used as a keyword, although could maybe be seen as a short form of `switch' statement, in which case `switch` should be treated as a keyword and not translated or capitalized. - PR Review Comment: https://git.openjdk.org/jdk/pull/19609#discussion_r1633782242
Re: RFR: 8333827: JDK 23 RDP1 L10n resource files update
On Sun, 9 Jun 2024 22:07:44 GMT, Damon Nguyen wrote:
>> src/jdk.jshell/share/classes/jdk/internal/jshell/tool/resources/l10n_de.properties
>> line 183:
>>
>>> 181: jshell.fix.wrong.shortcut =Unerwartetes Zeichen nach
>>> Umschalt+Tab.\nVerwenden Sie "I" für automatischen Import, "V" zur
>>> Variablenerstellung oder "M" zur Methodenerstellung.\nWeitere Informationen
>>> finden Sie unter:\n/help shortcuts
>>> 182:
>>> 183: help.usage = Verwendung: jshell ... ...\nMögliche
>>> Optionen:\n--class-pathGibt an, wo die Benutzerklassendateien
>>> gespeichert sind\n--module-path Gibt an, wo die
>>> Anwendungsmodule gespeichert sind\n--add-modules (,)*\n
>>> Gibt aufzulösende Module oder alle Module im\n
>>>Modulpfad an, wenn ALL-MODULE-PATHs
>>> lautet\n--enable-native-access\n Ermöglicht
>>> Ausführung eingeschränkter nativer Methoden durch Code\n
>>> --enable-preview Code kann Vorschaufeatures in diesem Release nutzen\n
>>>--startup Ersetzung der Startdefinitionen mit einer
>>> Ausführung\n--no-startup Startdefinitionen werden nicht
>>> ausgeführt\n--feedback Gibt den anfänglichen Feedbackmodus
>>> an. Der Modus kann\nvordefiniert (Silent,
>>> Concise, Normal oder Verbose) oder\n
vorab benutzerdefiniert sein\n-qStilles Feedback.
Identisch mit: --feedback concise\n-sÄußerst stilles
Feedback. Identisch mit: --feedback silent\n-v
Verbose-Feedback. Identisch mit: --feedback verbose\n-J
Übergibt an das Laufzeitsystem, hat aber keine Auswirkungen\n
auf die Ausführung von Code-Snippets. Um Kennzeichen
anzugeben,\ndie die Ausführung von Code-Snippets
beeinflussen, verwenden Sie\n-R. Verwenden
Sie alternativ dazu -J mit\n--execution
local.\n-R Übergibt nur dann an das
Laufzeitsystem, wenn\nCode-Snippets ausgeführt
werden. Beispiel: -R-Dfoo=bar\nbedeutet, dass die
Ausführung des Snippets\nSystem.getProperty("foo")
"bar" zurück
gibt.\n-C Übergibt an den Java-Compiler in
JShell.\nBeispiel: -C-Xlint aktiviert alle
empfohlenen\n...
>
> This is what I've determined as well. I planned to leave these untranslated
> to reduce noise between drops as well.
While we do not translate Java keywords (when used as such, e.g. "`class` not
allowed here"), and option names (e.g. `--class-path`) we have typically
translated other text that is not mandated by the language or tools, (e.g. `the
name of this class`, ``, ``.
This change seems to be going backwards.
Whatever the policy we use for translating (or not translating) parts of a
message, we should be consistent across all tools and documents.
-
PR Review Comment: https://git.openjdk.org/jdk/pull/19609#discussion_r1633774912
Re: RFR: 8330205: Initial troff manpage generation for JDK 24
On Tue, 7 May 2024 11:53:19 GMT, Pavel Rappo wrote: > Please review this mechanical change to man pages. This PR should be > integrated after https://github.com/openjdk/jdk/pull/18787. Marked as reviewed by jjg (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/19119#pullrequestreview-2044314419
Integrated: 8303689: javac -Xlint could/should report on "dangling" doc comments
On Wed, 27 Mar 2024 22:04:30 GMT, Jonathan Gibbons wrote:
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
This pull request has now been integrated.
Changeset: a920af23
Author:Jonathan Gibbons
URL:
https://git.openjdk.org/jdk/commit/a920af233a11592af113f456f7608cb59dd1617e
Stats: 482 lines in 58 files changed: 385 ins; 3 del; 94 mod
8303689: javac -Xlint could/should report on "dangling" doc comments
Reviewed-by: vromero, ihse, prr
-
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v10]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
fix typo
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/39689a52..48e8b0a2
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=09
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=08-09
Stats: 1 line in 1 file changed: 0 ins; 0 del; 1 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v9]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
revert need to disable warning
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/16a265a2..39689a52
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=08
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=07-08
Stats: 3 lines in 1 file changed: 0 ins; 2 del; 1 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v8]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
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:
- Merge remote-tracking branch 'upstream/master' into
8303689.dangling-comments # Please enter a commit message to explain why this
merge is necessary, # especially if it merges an updated upstream into a topic
branch. # # Lines starting with '#' will be ignored, and an empty message
aborts # the
commit.
- Merge with upstream/master
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge with upstream/master
- update test
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- ... and 1 more: https://git.openjdk.org/jdk/compare/1c238d43...16a265a2
-
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=07
Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v7]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request with a new target base due to a
merge or a rebase. The pull request now contains 10 commits:
- Merge with upstream/master
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- Merge with upstream/master
- update test
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
-
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=06
Stats: 485 lines in 59 files changed: 387 ins; 3 del; 95 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v6]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request with a new target base due to a
merge or a rebase. The pull request now contains seven commits:
- Merge with upstream/master
- update test
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
-
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=05
Stats: 488 lines in 61 files changed: 389 ins; 3 del; 96 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v5]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
update test
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/f3670e7a..8ad8b818
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=04
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=03-04
Stats: 6 lines in 1 file changed: 6 ins; 0 del; 0 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v4]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons 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 five additional
commits since the last revision:
- improve handling of ignorable doc comments
suppress warning when building test code
- Merge remote-tracking branch 'upstream/master' into 8303689.dangling-comments
- call `saveDanglingDocComments` for local variable declarations
- adjust call for `saveDanglingDocComments` for enum members
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/3f745431..f3670e7a
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=03
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=02-03
Stats: 42074 lines in 1058 files changed: 18282 ins; 15937 del; 7855 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v3]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
call `saveDanglingDocComments` for local variable declarations
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/56d6dcac..3f745431
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=02
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=01-02
Stats: 10 lines in 1 file changed: 5 ins; 2 del; 3 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v2]
On Wed, 3 Apr 2024 10:01:37 GMT, Magnus Ihse Bursie wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> adjust call for `saveDanglingDocComments` for enum members > > The build changes look okay. > > Do you have any plan of going through all the Java modules and fixing the > issues, or opening JBS issues to have them fixed? Or will these lint warnings > remain disabled for the foreseeable future? @magicus > The build changes look okay. > > Do you have any plan of going through all the Java modules and fixing the > issues, or opening JBS issues to have them fixed? Or will these lint warnings > remain disabled for the foreseeable future? The plan is to create an umbrella bug to clean up the individual modules. There is interest to clean up `java.base`, to keep that one free of any warnings, and I can see that the lang tools modules will get cleaner up as well. It will be up to other component teams to decide if and when to clean up other parts of the system. Once this work has been integrated, it is relatively easy to enable the warnings for a module and to fix the ensuing issues. Since any changes "only" involve comments, it should be reasonably easy to fix them, unlike some pervasive other warnings, like `this-escape`. - PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2052174696
Re: RFR: 8303689: javac -Xlint could/should report on "dangling" doc comments [v2]
> Please review the updates to support a proposed new
> `-Xlint:dangling-doc-comments` option.
>
> The work can be thought of as in 3 parts:
>
> 1. An update to the `javac` internal class `DeferredLintHandler` so that it
> is possible to specify the appropriately configured `Lint` object when it is
> time to consider whether to generate the diagnostic or not.
>
> 2. Updates to the `javac` front end to record "dangling docs comments" found
> near the beginning of a declaration, and to report them using an instance of
> `DeferredLintHandler`. This allows the warnings to be enabled or disabled
> using the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The
> procedure for handling dangling doc comments is described in this comment in
> `JavacParser`.
>
> * Dangling documentation comments are handled as follows.
> * 1. {@code Scanner} adds all doc comments to a queue of
> * recent doc comments. The queue is flushed whenever
> * it is known that the recent doc comments should be
> * ignored and should not cause any warnings.
> * 2. The primary documentation comment is the one obtained
> * from the first token of any declaration.
> * (using {@code token.getDocComment()}.
> * 3. At the end of the "signature" of the declaration
> * (that is, before any initialization or body for the
> * declaration) any other "recent" comments are saved
> * in a map using the primary comment as a key,
> * using this method, {@code saveDanglingComments}.
> * 4. When the tree node for the declaration is finally
> * available, and the primary comment, if any,
> * is "attached", (in {@link #attach}) any related
> * dangling comments are also attached to the tree node
> * by registering them using the {@link #deferredLintHandler}.
> * 5. (Later) Warnings may be genereated for the dangling
> * comments, subject to the {@code -Xlint} and
> * {@code @SuppressWarnings}.
>
>
> 3. Updates to the make files to disable the warnings in modules for which
> the
> warning is generated. This is often because of the confusing use of `/**` to
> create box or other standout comments.
Jonathan Gibbons has updated the pull request incrementally with one additional
commit since the last revision:
adjust call for `saveDanglingDocComments` for enum members
-
Changes:
- all: https://git.openjdk.org/jdk/pull/18527/files
- new: https://git.openjdk.org/jdk/pull/18527/files/3d6f1f95..56d6dcac
Webrevs:
- full: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=01
- incr: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=00-01
Stats: 5 lines in 1 file changed: 3 ins; 2 del; 0 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
On Wed, 27 Mar 2024 22:41:33 GMT, Pavel Rappo wrote: > Would this be the first lint -- not doclint -- warning related to comments, > let alone doc comments? No. `-Xlint:dep-ann` correlates `@Deprecated` annotations with `@deprecated` tags in doc comments. > src/jdk.javadoc/share/man/javadoc.1 line 111: > >> 109: source code with the \f[V]javac\f[R] option \f[V]-Xlint\f[R], or more >> 110: specifically, \f[V]-Xlint:dangling-doc-comments\f[R]. >> 111: Within a source file, you may use suppress any warnings generated by > > Typo? > Suggestion: > > Within a source file, you may suppress any warnings generated by Thanks; I'll check the underlying original. - PR Comment: https://git.openjdk.org/jdk/pull/18527#issuecomment-2024162355 PR Review Comment: https://git.openjdk.org/jdk/pull/18527#discussion_r1542157047
RFR: JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
Please review the updates to support a proposed new
`-Xlint:dangling-doc-comments` option.
The work can be thought of as in 3 parts:
1. An update to the `javac` internal class `DeferredLintHandler` so that it is
possible to specify the appropriately configured `Lint` object when it is time
to consider whether to generate the diagnostic or not.
2. Updates to the `javac` front end to record "dangling docs comments" found
near the beginning of a declaration, and to report them using an instance of
`DeferredLintHandler`. This allows the warnings to be enabled or disabled using
the standard mechanisms for `-Xlint` and `@SuppressWarnings`. The procedure
for handling dangling doc comments is described in this comment in
`JavacParser`.
* Dangling documentation comments are handled as follows.
* 1. {@code Scanner} adds all doc comments to a queue of
* recent doc comments. The queue is flushed whenever
* it is known that the recent doc comments should be
* ignored and should not cause any warnings.
* 2. The primary documentation comment is the one obtained
* from the first token of any declaration.
* (using {@code token.getDocComment()}.
* 3. At the end of the "signature" of the declaration
* (that is, before any initialization or body for the
* declaration) any other "recent" comments are saved
* in a map using the primary comment as a key,
* using this method, {@code saveDanglingComments}.
* 4. When the tree node for the declaration is finally
* available, and the primary comment, if any,
* is "attached", (in {@link #attach}) any related
* dangling comments are also attached to the tree node
* by registering them using the {@link #deferredLintHandler}.
* 5. (Later) Warnings may be genereated for the dangling
* comments, subject to the {@code -Xlint} and
* {@code @SuppressWarnings}.
3. Updates to the make files to disable the warnings in modules for which the
warning is generated. This is often because of the confusing use of `/**` to
create box or other standout comments.
-
Commit messages:
- JDK-8303689: javac -Xlint could/should report on "dangling" doc comments
Changes: https://git.openjdk.org/jdk/pull/18527/files
Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=18527&range=00
Issue: https://bugs.openjdk.org/browse/JDK-8303689
Stats: 477 lines in 60 files changed: 368 ins; 5 del; 104 mod
Patch: https://git.openjdk.org/jdk/pull/18527.diff
Fetch: git fetch https://git.openjdk.org/jdk.git pull/18527/head:pull/18527
PR: https://git.openjdk.org/jdk/pull/18527
Re: RFR: 8267174: Many test files have the wrong Copyright header
On Tue, 5 Sep 2023 22:49:41 GMT, Erik Joelsson wrote: > There are a number of files in the `test` directory that have an incorrect > copyright header, which includes the "classpath" exception text. This patch > removes that text from all test files that I could find it in. I did this > using a combination of `sed` and `grep`. Reviewing this patch is probably > easier using the raw patch file or a suitable webrev format. > > It's my assumption that these headers were introduced by mistake as it's > quite easy to copy the wrong template when creating new files. One has to wonder about the `**/*_OLD.java` files, but that would be a different cleanup - PR Review: https://git.openjdk.org/jdk/pull/15573#pullrequestreview-1612069262
Re: RFR: 8310988: Missing @since tags in java.management.rmi
On Thu, 29 Jun 2023 16:08:15 GMT, Kevin Walls wrote: > Simple doc tag addition. > > These are files which describe an interface that has been with us since 1.5. > The files themselves were previously generated at build time, but have been > in the repo since jdk15. But the API is since 1.5. > > The other file mentioned in the bug is not a public class and has no javadoc > generated, ignoring that one. Marked as reviewed by jjg (Reviewer). - PR Review: https://git.openjdk.org/jdk/pull/14714#pullrequestreview-1505775865
Re: RFR: 8309632: JDK 21 RDP1 L10n resource files update [v2]
On Tue, 13 Jun 2023 18:38:28 GMT, Naoto Sato wrote: > Left some comments on the translations mainly in Japanese. It is now very > easy to look at the l10n changes in the generated HTML. One small comment to > the tool is that it would be nice if the order in HTML (alphabetically sorted > currently) aligns with the order in the actual resource file. It is a great > improvement anyways. 1. It is not easy to recover the order in the actual resource file: the contents are read into a `Properties` object which uses a `Hashtable` to store the data. 2. There is no guarantee that the order is the same in all the resource files, so we would have to choose one, presumably the default one, to determine the presentation order. - PR Comment: https://git.openjdk.org/jdk/pull/14430#issuecomment-1594844435
Re: RFR: JDK-8305713: DocCommentParser: merge blockContent and inlineContent [v3]
> Please review a cleanup in DocCommentParser to merge blockContent and > inlineContent into a single method to parse "rich content" in a doc comment. Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains 59 commits: - Merge branch 'pr/13362' into pr/13362 - Merge remote-tracking branch 'upstream/master' into 8305713.dcp-content - 8305809: (fs) Review obsolete Linux kernel dependency on os.version (Unix kernel 2.6.39) Reviewed-by: rriggs, alanb - 8294806: jpackaged-app ignores splash screen from jar file Reviewed-by: almatvee - 8305368: G1 remset chunk claiming may use relaxed memory ordering Reviewed-by: ayang, iwalulya - 8305370: Inconsistent use of for_young_only_phase parameter in G1 predictions Reviewed-by: iwalulya, kbarrett - 8305663: Wrong iteration order of pause array in g1MMUTracker Reviewed-by: ayang, tschatzl - 8305761: Resolve multiple definition of 'jvm' when statically linking with JDK native libraries Reviewed-by: alanb, kevinw - 8305419: JDK-8301995 broke building libgraal Reviewed-by: matsaave, dnsimon, thartmann - 8302696: Revert API signature changes made in JDK-8285504 and JDK-8285263 Reviewed-by: mullan - ... and 49 more: https://git.openjdk.org/jdk/compare/5501bf21...45ee028b - Changes: https://git.openjdk.org/jdk/pull/13431/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=13431&range=02 Stats: 15292 lines in 500 files changed: 7710 ins; 6358 del; 1224 mod Patch: https://git.openjdk.org/jdk/pull/13431.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/13431/head:pull/13431 PR: https://git.openjdk.org/jdk/pull/13431
Re: RFR: JDK-8305713: DocCommentParser: merge blockContent and inlineContent [v2]
> Please review a cleanup in DocCommentParser to merge blockContent and > inlineContent into a single method to parse "rich content" in a doc comment. Jonathan Gibbons has updated the pull request incrementally with 42 additional commits since the last revision: - Merge remote-tracking branch 'upstream/master' into 8305713.dcp-content - 8305809: (fs) Review obsolete Linux kernel dependency on os.version (Unix kernel 2.6.39) Reviewed-by: rriggs, alanb - 8294806: jpackaged-app ignores splash screen from jar file Reviewed-by: almatvee - 8305368: G1 remset chunk claiming may use relaxed memory ordering Reviewed-by: ayang, iwalulya - 8305370: Inconsistent use of for_young_only_phase parameter in G1 predictions Reviewed-by: iwalulya, kbarrett - 8305663: Wrong iteration order of pause array in g1MMUTracker Reviewed-by: ayang, tschatzl - 8305761: Resolve multiple definition of 'jvm' when statically linking with JDK native libraries Reviewed-by: alanb, kevinw - 8305419: JDK-8301995 broke building libgraal Reviewed-by: matsaave, dnsimon, thartmann - 8302696: Revert API signature changes made in JDK-8285504 and JDK-8285263 Reviewed-by: mullan - 8304738: UnregisteredClassesTable_lock never created Reviewed-by: iklam, jcking, dholmes - ... and 32 more: https://git.openjdk.org/jdk/compare/b8b43eae...ab56c463 - Changes: - all: https://git.openjdk.org/jdk/pull/13431/files - new: https://git.openjdk.org/jdk/pull/13431/files/b8b43eae..ab56c463 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=13431&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=13431&range=00-01 Stats: 9487 lines in 384 files changed: 2654 ins; 5914 del; 919 mod Patch: https://git.openjdk.org/jdk/pull/13431.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/13431/head:pull/13431 PR: https://git.openjdk.org/jdk/pull/13431
RFR: JDK-8305713: DocCommentParser: merge blockContent and inlineContent
Please review a cleanup in DocCommentParser to merge blockContent and inlineContent into a single method to parse "rich content" in a doc comment. - Depends on: https://git.openjdk.org/jdk/pull/13362 Commit messages: - JDK-8305713: DocCommentParser: merge blockContent and inlineContent - 8272119: Typo in JDK documentation (a -> an) - 8305461: [vectorapi] Add VectorMask::xor - 8305608: Change VMConnection to use "test.class.path"instead of "test.classes" - 8274166: Some CDS tests ignore -Dtest.cds.runtime.options - 8304745: Lazily initialize byte[] in java.io.BufferedInputStream - 8267140: Support closing the HttpClient by making it auto-closable - 8269843: typo in LinkedHashMap::removeEldestEntry spec - 8305480: test/hotspot/jtreg/runtime/NMT/VirtualAllocCommitMerge.java failing on 32 bit arm - 8305607: Remove some unused test parameters in com/sun/jdi tests - ... and 6 more: https://git.openjdk.org/jdk/compare/44f33ad1...b8b43eae Changes: https://git.openjdk.org/jdk/pull/13431/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=13431&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8305713 Stats: 5934 lines in 119 files changed: 5071 ins; 480 del; 383 mod Patch: https://git.openjdk.org/jdk/pull/13431.diff Fetch: git fetch https://git.openjdk.org/jdk.git pull/13431/head:pull/13431 PR: https://git.openjdk.org/jdk/pull/13431
Re: RFR: 8301991: Convert l10n properties resource bundles to UTF-8 native
On Thu, 23 Feb 2023 09:04:23 GMT, Justin Lu wrote:
> This PR converts Unicode sequences to UTF-8 native in .properties file.
> (Excluding the Unicode space and tab sequence). The conversion was done using
> native2ascii.
>
> In addition, the build logic is adjusted to support reading in the
> .properties files as UTF-8 during the conversion from .properties file to
> .java ListResourceBundle file.
make/langtools/tools/compileproperties/CompileProperties.java line 252:
> 250: try {
> 251: writer = new BufferedWriter(
> 252: new OutputStreamWriter(new
> FileOutputStream(outputPath), StandardCharsets.ISO_8859_1));
Using ISO_8859_1 seems strange.
Since these are generated files, you could write them as UTF-8 and then
override the default javac option for ascii when compiling _just_ these files.
Or else just stay with ascii; no one should be looking at these files!
-
PR: https://git.openjdk.org/jdk/pull/12726
Re: RFR: 8303480: Miscellaneous fixes to mostly invisible doc comments [v2]
On Mon, 6 Mar 2023 20:22:48 GMT, Pavel Rappo wrote: >> Please review this superficial documentation cleanup that was triggered by >> unrelated analysis of doc comments in JDK API. >> >> The only effect that this multi-area PR has on the JDK API Documentation >> (i.e. the observable effect on the generated HTML pages) can be summarized >> as follows: >> >> >> diff -ur >> build/macosx-aarch64/images/docs-before/api/serialized-form.html >> build/macosx-aarch64/images/docs-after/api/serialized-form.html >> --- build/macosx-aarch64/images/docs-before/api/serialized-form.html >> 2023-03-02 11:47:44 >> +++ build/macosx-aarch64/images/docs-after/api/serialized-form.html >> 2023-03-02 11:48:45 >> @@ -17084,7 +17084,7 @@ >> throws > href="java.base/java/io/IOException.html" title="class in >> java.io">IOException, >> ClassNotFoundException >> readObject is called to restore the >> state of the >> - (@code BasicPermission} from a stream. >> + BasicPermission from a stream. >> >> Parameters: >> s - the ObjectInputStream from which data >> is read >> >> Notes >> - >> >> * I'm not an expert in any of the affected areas, except for jdk.javadoc, >> and I was merely after misused tags. Because of that, I would appreciate >> reviews from experts in other areas. >> * I discovered many more issues than I included in this PR. The excluded >> issues seem to occur in infrequently updated third-party code (e.g. >> javax.xml), which I assume we shouldn't touch unless necessary. >> * I will update copyright years after (and if) the fix had been approved, as >> required. > > Pavel Rappo 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 two additional > commits since the last revision: > > - Merge branch 'master' into 8303480 > - Initial commit Marked as reviewed by jjg (Reviewer). - PR: https://git.openjdk.org/jdk/pull/12826
Re: RFR: 8303480: Miscellaneous fixes to mostly invisible doc comments [v2]
On Fri, 3 Mar 2023 11:31:04 GMT, Alexey Ivanov wrote: >> Yes, iff means if-and-only-if and is used for extra precision in formal >> logic, mathematics. As @pavelrappo points out it's a relatively common >> occurrence in the OpenJDK sources, though perhaps not in the public >> javadocs. Perhaps a bit pretentious, but mostly a terse way to say "return >> true if the BSM method type exactly matches X, otherwise false". >> >> The broken link stems from the fact that the method I was targeting (a way >> to use condy for lambda proxy singletons rather than a >> `MethodHandle.constant`) was never integrated. We'll look at either getting >> that done (@briangoetz suggested the time might be ready for it) or remove >> this currently pointless static bootstrap specialization test. > >> Yes, iff means if-and-only-if and is used for extra precision in formal >> logic, mathematics. > > I've never come across it before. With your explanations, it makes perfect > sense. I would recommend (separately) changing `iff` to the expanded form `if and only if` - PR: https://git.openjdk.org/jdk/pull/12826
Re: [jdk20] RFR: 8300719: JDK 20 RDP2 L10n resource files update [v5]
On Wed, 25 Jan 2023 20:03:48 GMT, Pavel Rappo wrote: >> I'm not sure either. You can ask a javadoc expert whether this is a proper >> noun or just plain English. I noticed it's also not translated in the >> Japanese version but the German version has translated it. > > It's not a noun. It's an adjective that I had to synthesize for extra clarity > and closeness to Java Language Specification (JLS). The English version of > that entry is as follows: > > doclet.throwsInheritDocUnsupported=@inheritDoc is not supported for > exception-type type parameters \ > that are not declared by a method; document such exception types directly > > JLS _8.4.6. Method Throws_ defines BNF which conveniently labels elements, a > list of which may appear in the `throws` clause, as `ExceptionType`. To make > it more English-like and separate two otherwise consecutive occurrences of > "type" in that sentence, I split the words with a hyphen and lower-cased > them: exception-type. > > @jonathan-gibbons thoughts? While the text is technically correct, it may not be as clear as it could be to all folk that will read this message for whom English is not their primary language. I would suggest translating the phrase as if it were something like @inheritDoc is not supported for type parameters that are exception types and not declared by a method and secondarily, changing the English resource to something like that as well. - PR: https://git.openjdk.org/jdk20/pull/116
Re: [jdk20] RFR: 8300719: JDK 20 RDP2 L10n resource files update [v7]
On Wed, 25 Jan 2023 17:51:20 GMT, Damon Nguyen wrote: >> Open l10n drop. Files have been updated with translated versions. Whitespace >> tool has been ran on files. >> All tests passed > > Damon Nguyen has updated the pull request incrementally with one additional > commit since the last revision: > > Revert one more punctuation I don't see anything absurdly wrong in the jdk.compiler files. - Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.org/jdk20/pull/116
Re: RFR: 8296546: Add @spec tags to API [v4]
On Thu, 10 Nov 2022 23:51:19 GMT, Naoto Sato wrote: >> Jonathan Gibbons 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 five additional >> commits since the last revision: >> >> - Change ietf.org URLs to use rfc-editor.org >> - Merge remote-tracking branch 'upstream/master' into 8296546.add-spec-tags >> - Remove updates from unexported files >> - Prefix RFC titles with `RFC :` >> - JDK-8296547: Add @spec tags to API > > src/java.base/share/classes/java/lang/Character.java line 172: > >> 170: * occur. For example, in a future release, synchronization may fail. >> 171: * >> 172: * @spec https://www.unicode.org/reports/tr27 Unicode 3.1.0 > > This should probably be removed, as the original link (explaining `U+n` > notation) is broken. @naotoj The edits are driven by a script, using info about existing links in the same doc comment. If you don't think this reference is appropriate, it would be better to either remove the existing link (and I'll regenerate this patch) or else this patch goes through and you fix up both the existing link and the `@spec` tag afterwards. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 23:04:36 GMT, Joe Wang wrote: >> Jonathan Gibbons has updated the pull request incrementally with one >> additional commit since the last revision: >> >> Remove updates from unexported files > > src/java.xml/share/classes/javax/xml/XMLConstants.java line 35: > >> 33: * @spec https://www.w3.org/TR/REC-xml-names Namespaces in XML 1.0 >> (Third Edition) >> 34: * @spec https://www.w3.org/TR/xml-names11 Namespaces in XML 1.1 (Second >> Edition) >> 35: * @spec https://www.w3.org/TR/xmlschema-1 XML Schema Part 1: Structures >> Second Edition > > Hi Jon, > > I would agree with what Alan said earlier that the @see ref can be dropped. > This particular class (XMLConstants.java [1]) is a good example for that > argument: in the resulting javadoc, 5 specs were listed in the "External > Specifications" section, 6 in "See Also:", and then they were listed again > for each field. That's a lot of duplicates. Adding to the confusion was that > the @spec and @see were not always the same, e.g. @spec XML 1.0. > points to the fifth edition while @see second. > > A minor comment is that the '@spec's were rendered in one line while the @see > refs a list. I would see the later is easier to read. > > [1] > http://cr.openjdk.java.net/~jjg/8296546/api.00/java.xml/javax/xml/XMLConstants.html The presentation of lists of `@spec` tags was fixed separately (JDK-8297802), and is incorporated into the latest docs that demo this work. The same algorithm is now used for both `@see` and `@spec` tags ... if the links are short and do not contain commas, they will be displayed as an inline list; otherwise, they will be displayed in a bulleted list. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v4]
> Please review a "somewhat automated" change to insert `@spec` tags into doc > comments, as appropriate, to leverage the recent new javadoc feature to > generate a new page listing the references to all external specifications > listed in the `@spec` tags. > > "Somewhat automated" means that I wrote and used a temporary utility to scan > doc comments looking for HTML links to selected sites, such as `ietf.org`, > `unicode.org`, `w3.org`. These links may be in the main description of a doc > comment, or in `@see` tags. For each link, the URL is examined, and > "normalized", and inserted into the doc comment with a new `@spec` tag, > giving the link and tile for the spec. > > "Normalized" means... > * Use `https:` where possible (includes pretty much all cases) > * Use a single consistent host name for all URLs coming from the same spec > site (i.e. don't use different aliases for the same site) > * Point to the root page of a multi-page spec > * Use a consistent form of the spec, preferring HTML over plain text where > both are available (this mostly applies to IETF specs) > > In addition, a "standard" title is determined for all specs, determined > either from the content of the (main) spec page or from site index pages. > > The net effect is (or should be) that **all** the changes are to just **add** > new `@spec` tags, based on the links found in each doc comment. There should > be no other changes to the doc comments, or to the implementation of any > classes and interfaces. > > That being said, the utility I wrote does have additional abilities, to > update the links that it finds (e.g. changing to use `https:` etc,) but those > features are _not_ being used here, but could be used in followup PRs if > component teams so desired. I did notice while working on this overall > feature that many of our links do point to "outdated" pages, some with > eye-catching notices declaring that the spec has been superseded. Determining > how, when and where to update such links is beyond the scope of this PR. > > Going forward, it is to be hoped that component teams will maintain the > underlying links, and the URLs in `@spec` tags, such that if references to > external specifications are updated, this will include updating the `@spec` > tags. > > To see the effect of all these new `@spec` tags, see > http://cr.openjdk.java.net/~jjg/8296546/api.00/ > > In particular, see the new [External > Specifications](http://cr.openjdk.java.net/~jjg/8296546/api.00/external-specs.html) > page, which you can also find via the new link near the top of the > [Index](http://cr.openjdk.java.net/~jjg/8296546/api.00/index-files/index-1.html) > pages. Jonathan Gibbons 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 five additional commits since the last revision: - Change ietf.org URLs to use rfc-editor.org - Merge remote-tracking branch 'upstream/master' into 8296546.add-spec-tags - Remove updates from unexported files - Prefix RFC titles with `RFC :` - JDK-8296547: Add @spec tags to API - Changes: - all: https://git.openjdk.org/jdk/pull/11073/files - new: https://git.openjdk.org/jdk/pull/11073/files/3905ac83..07882ffc Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=03 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=02-03 Stats: 83309 lines in 1834 files changed: 38491 ins; 27762 del; 17056 mod Patch: https://git.openjdk.org/jdk/pull/11073.diff Fetch: git fetch https://git.openjdk.org/jdk pull/11073/head:pull/11073 PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
On Wed, 23 Nov 2022 19:20:53 GMT, Daniel Fuchs wrote:
> The java.base/net/, java.http/, java.naming/ changes look reasonable to me -
> though like Alan I wonder if it wouldn't be better to have an inline `{@spec
> }` tag - similar to `{@systemProperty }`, rather than repeating all the
> references outside of the context where they were cited. This probably also
> calls for a review of these references by maintainers of the various areas -
> as some of them might need some updating - e.g. linking to `rfceditor` as was
> previously suggested, and double checking whether all of them still make
> sense. Not something to be conducted within this PR though.
Believe me, I tried *very* hard to design and use an inline `{@spec}` tag but
such a tag effectively needs a normative external file to indicate the root of
a multi-page spec, and the definitive title, since inline tags either do not or
are unlikely to contain such information.
The general history of this work is:
* version 1: bimodal tag with no external file -- the content of the summary
page was effectively rubbish
* version 2: bimodal tag with an external file -- in discussion with @jddarcy
and CSR, we decided that was too much of a non-standard maintenance load
* version 3: new tag, with no external file needed -- as you see here
-
PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v3]
> Please review a "somewhat automated" change to insert `@spec` tags into doc > comments, as appropriate, to leverage the recent new javadoc feature to > generate a new page listing the references to all external specifications > listed in the `@spec` tags. > > "Somewhat automated" means that I wrote and used a temporary utility to scan > doc comments looking for HTML links to selected sites, such as `ietf.org`, > `unicode.org`, `w3.org`. These links may be in the main description of a doc > comment, or in `@see` tags. For each link, the URL is examined, and > "normalized", and inserted into the doc comment with a new `@spec` tag, > giving the link and tile for the spec. > > "Normalized" means... > * Use `https:` where possible (includes pretty much all cases) > * Use a single consistent host name for all URLs coming from the same spec > site (i.e. don't use different aliases for the same site) > * Point to the root page of a multi-page spec > * Use a consistent form of the spec, preferring HTML over plain text where > both are available (this mostly applies to IETF specs) > > In addition, a "standard" title is determined for all specs, determined > either from the content of the (main) spec page or from site index pages. > > The net effect is (or should be) that **all** the changes are to just **add** > new `@spec` tags, based on the links found in each doc comment. There should > be no other changes to the doc comments, or to the implementation of any > classes and interfaces. > > That being said, the utility I wrote does have additional abilities, to > update the links that it finds (e.g. changing to use `https:` etc,) but those > features are _not_ being used here, but could be used in followup PRs if > component teams so desired. I did notice while working on this overall > feature that many of our links do point to "outdated" pages, some with > eye-catching notices declaring that the spec has been superseded. Determining > how, when and where to update such links is beyond the scope of this PR. > > Going forward, it is to be hoped that component teams will maintain the > underlying links, and the URLs in `@spec` tags, such that if references to > external specifications are updated, this will include updating the `@spec` > tags. > > To see the effect of all these new `@spec` tags, see > http://cr.openjdk.java.net/~jjg/8296546/api.00/ > > In particular, see the new [External > Specifications](http://cr.openjdk.java.net/~jjg/8296546/api.00/external-specs.html) > page, which you can also find via the new link near the top of the > [Index](http://cr.openjdk.java.net/~jjg/8296546/api.00/index-files/index-1.html) > pages. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Remove updates from unexported files - Changes: - all: https://git.openjdk.org/jdk/pull/11073/files - new: https://git.openjdk.org/jdk/pull/11073/files/c29092d8..3905ac83 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=02 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=01-02 Stats: 34 lines in 25 files changed: 0 ins; 34 del; 0 mod Patch: https://git.openjdk.org/jdk/pull/11073.diff Fetch: git fetch https://git.openjdk.org/jdk pull/11073/head:pull/11073 PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8296546: Add @spec tags to API [v2]
On Wed, 23 Nov 2022 12:43:16 GMT, Daniel Fuchs wrote: > Thanks for adding the RFC prefix to the RFC link. What is the purpose of > editing non exported classes though, like those in the `sun.net` subpackages? That was not intentional, and is a result of the scripted edit. I will look to revert those changes and/or change the tooling to ignore those packages. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8295424: adjust timeout for another JLI GetObjectSizeIntrinsicsTest.java subtest
On Tue, 22 Nov 2022 21:05:16 GMT, Daniel D. Daugherty wrote: >> test/langtools/jdk/javadoc/doclet/testLinkOption/TestRedirectLinks.java line >> 73: >> >>> 71: >>> 72: import jdk.test.lib.Platform; >>> 73: import jtreg.SkippedException; >> >> Nit: the order of imports on 72-73 needs to be swapped. > > Why? 'jdk' comes before 'jtreg' and 'Platform' comes before > 'SkippedException'. > What am I missing here? Mild grumble: langtools tests do not rely on jdk test libraries - PR: https://git.openjdk.org/jdk/pull/11278
Re: RFR: 8295424: adjust timeout for another JLI GetObjectSizeIntrinsicsTest.java subtest
On Mon, 21 Nov 2022 22:55:40 GMT, Daniel D. Daugherty wrote: > Misc stress testing related fixes: > > [JDK-8295424](https://bugs.openjdk.org/browse/JDK-8295424) adjust timeout for > another JLI GetObjectSizeIntrinsicsTest.java subtest > [JDK-8297367](https://bugs.openjdk.org/browse/JDK-8297367) disable > TestRedirectLinks.java in slowdebug mode > [JDK-8297369](https://bugs.openjdk.org/browse/JDK-8297369) disable Fuzz.java > in slowdebug mode I accept the javadoc change but dislike the general methodology: it's too much like brushing the dirt under the carpet. In general, I think it is better to use keywords, or `@require` to mark such tests and then (if using keywords) use command-line options to filter out such tests. - Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.org/jdk/pull/11278
Re: RFR: 8296546: Add @spec tags to API [v2]
> Please review a "somewhat automated" change to insert `@spec` tags into doc > comments, as appropriate, to leverage the recent new javadoc feature to > generate a new page listing the references to all external specifications > listed in the `@spec` tags. > > "Somewhat automated" means that I wrote and used a temporary utility to scan > doc comments looking for HTML links to selected sites, such as `ietf.org`, > `unicode.org`, `w3.org`. These links may be in the main description of a doc > comment, or in `@see` tags. For each link, the URL is examined, and > "normalized", and inserted into the doc comment with a new `@spec` tag, > giving the link and tile for the spec. > > "Normalized" means... > * Use `https:` where possible (includes pretty much all cases) > * Use a single consistent host name for all URLs coming from the same spec > site (i.e. don't use different aliases for the same site) > * Point to the root page of a multi-page spec > * Use a consistent form of the spec, preferring HTML over plain text where > both are available (this mostly applies to IETF specs) > > In addition, a "standard" title is determined for all specs, determined > either from the content of the (main) spec page or from site index pages. > > The net effect is (or should be) that **all** the changes are to just **add** > new `@spec` tags, based on the links found in each doc comment. There should > be no other changes to the doc comments, or to the implementation of any > classes and interfaces. > > That being said, the utility I wrote does have additional abilities, to > update the links that it finds (e.g. changing to use `https:` etc,) but those > features are _not_ being used here, but could be used in followup PRs if > component teams so desired. I did notice while working on this overall > feature that many of our links do point to "outdated" pages, some with > eye-catching notices declaring that the spec has been superseded. Determining > how, when and where to update such links is beyond the scope of this PR. > > Going forward, it is to be hoped that component teams will maintain the > underlying links, and the URLs in `@spec` tags, such that if references to > external specifications are updated, this will include updating the `@spec` > tags. > > To see the effect of all these new `@spec` tags, see > http://cr.openjdk.java.net/~jjg/8296546/api.00/ > > In particular, see the new [External > Specifications](http://cr.openjdk.java.net/~jjg/8296546/api.00/external-specs.html) > page, which you can also find via the new link near the top of the > [Index](http://cr.openjdk.java.net/~jjg/8296546/api.00/index-files/index-1.html) > pages. Jonathan Gibbons has updated the pull request incrementally with one additional commit since the last revision: Prefix RFC titles with `RFC :` - Changes: - all: https://git.openjdk.org/jdk/pull/11073/files - new: https://git.openjdk.org/jdk/pull/11073/files/30ce235f..c29092d8 Webrevs: - full: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=01 - incr: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=00-01 Stats: 325 lines in 165 files changed: 4 ins; 4 del; 317 mod Patch: https://git.openjdk.org/jdk/pull/11073.diff Fetch: git fetch https://git.openjdk.org/jdk pull/11073/head:pull/11073 PR: https://git.openjdk.org/jdk/pull/11073
Integrated: JDK-8297164: Update troff man pages and CheckManPageOptions.java
On Thu, 17 Nov 2022 22:23:53 GMT, Jonathan Gibbons wrote: > Please review an update for the troff man pages, following the recent update > to upgrade to use pandoc 2.19.2 > (See https://bugs.openjdk.org/browse/JDK-8297165) > > In conjunction with this, one javadoc test also needs to be updated, to work > with the new form of output generated by the new version of pandoc. This pull request has now been integrated. Changeset: 5a45c251 Author: Jonathan Gibbons URL: https://git.openjdk.org/jdk/commit/5a45c25151b1da8e329ea2be21a0e4d2652f8b4a Stats: 8963 lines in 29 files changed: 471 ins; 1587 del; 6905 mod 8297164: Update troff man pages and CheckManPageOptions.java Reviewed-by: dholmes - PR: https://git.openjdk.org/jdk/pull/11223
Re: RFR: JDK-8297164: Update troff man pages and CheckManPageOptions.java [v2]
> Please review an update for the troff man pages, following the recent update > to upgrade to use pandoc 2.19.2 > (See https://bugs.openjdk.org/browse/JDK-8297165) > > In conjunction with this, one javadoc test also needs to be updated, to work > with the new form of output generated by the new version of pandoc. Jonathan Gibbons has updated the pull request with a new target base due to a merge or a rebase. The pull request now contains three commits: - Fix merge issue - Merge with upstream/master - JDK-8297164: Update troff man pages and CheckManPageOptions.java - Changes: https://git.openjdk.org/jdk/pull/11223/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=11223&range=01 Stats: 8963 lines in 29 files changed: 471 ins; 1587 del; 6905 mod Patch: https://git.openjdk.org/jdk/pull/11223.diff Fetch: git fetch https://git.openjdk.org/jdk pull/11223/head:pull/11223 PR: https://git.openjdk.org/jdk/pull/11223
Re: RFR: JDK-8297164: Update troff man pages and CheckManPageOptions.java
On Fri, 18 Nov 2022 02:31:19 GMT, David Holmes wrote: > Hi @jonathan-gibbons , > > I notice that in the new version dash characters are no longer escaped as > `-`, do these still display correctly? Yes, at least in all the files I verified and I have no reason to believe it might be different in any other files. On a Mac, you can just do `man ` to render the contents of a troff file. That is how I checked the files that I did. - PR: https://git.openjdk.org/jdk/pull/11223
RFR: JDK-8297164: Update troff man pages and CheckManPageOptions.java
Please review an update for the troff man pages, following the recent update to upgrade to use pandoc 2.19.2 (See https://bugs.openjdk.org/browse/JDK-8297165) In conjunction with this, one javadoc test also needs to be updated, to work with the new form of output generated by the new version of pandoc. - Commit messages: - JDK-8297164: Update troff man pages and CheckManPageOptions.java Changes: https://git.openjdk.org/jdk/pull/11223/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=11223&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8297164 Stats: 8944 lines in 29 files changed: 471 ins; 1589 del; 6884 mod Patch: https://git.openjdk.org/jdk/pull/11223.diff Fetch: git fetch https://git.openjdk.org/jdk pull/11223/head:pull/11223 PR: https://git.openjdk.org/jdk/pull/11223
Re: RFR: 8296546: Add @spec tags to API
On Thu, 10 Nov 2022 16:33:09 GMT, AJ1062910 wrote: > did you changed 420 files ? I ran a custom utility that edited these files, yes. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: JDK-8296546: Add @spec tags to API
On Thu, 10 Nov 2022 12:01:11 GMT, Alan Bateman wrote: > I'm trying to understand what "fix-ups" will be needed if the automated patch > is applied. In some cases, it looks the same spec will be linked from "See > also" and "External Specifications", e.g. > http://cr.openjdk.java.net/~jjg/8296546/api.00/java.base/java/net/StandardSocketOptions.html#TCP_NODELAY > so the `@see` ref can be dropped. > > In other cases we will have inline refs and the same URL in the `@spec`. This > may be okay for the short term but maybe there is a way to inline `@spec` to > avoid the duplication? > > There will probably be a bit of cleanup to reflow some lines, e.g. > StandardSocketOptions.java, as excessively long lines are problematic for > side-by-side diffs. The utility I mentioned has the (optional) ability to remove `@see` links when the text of the link exactly matches that used by the `@spec` tag. Unfortunately, the text is typically not exactly the same, and would require manual analysis to see if the `@see` tag can be removed. When inline references are used, the wording is very rarely the primary title of the spec: it is more likely to be a word or phrase that makes sense in the context of the enclosing sentence. _History: version 1 of this feature tried replacing inline links and `@see` tags with a bi-modal `@spec` tag. The results were "not good", especially in the generated external-specs page. Version 2 used a side file to provide the definitive title for each spec, but that was deemed to be too much of a maintenance issue. This is version 3, in which we've eliminated the side-file in favor of duplicating the title in each `@spec` tag._ - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: JDK-8296546: Add @spec tags to API
On Thu, 10 Nov 2022 11:45:39 GMT, Alan Bateman wrote: > > When referencing an RFC, it might be good to keep the RFC number in the > > text link. For instance I see that java.net.URL now has this: > > I agree and also to add that some RFCs have commas in their titles, the same > separator used when there is more than one specification linked. Here's an > example: > > http://cr.openjdk.java.net/~jjg/8296546/api.00/java.base/java/nio/channels/MulticastChannel.html I can change the doclet to use a bulleted list when any spec titles contain a comma. - PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: JDK-8296546: Add @spec tags to API
On Thu, 10 Nov 2022 11:30:51 GMT, Daniel Fuchs wrote: > Hi Jon, > > When referencing an RFC, it might be good to keep the RFC number in the text > link. For instance I see that java.net.URL now has this: > > http://cr.openjdk.java.net/~jjg/8296546/api.00/java.base/java/net/URL.html > > External Specifications [Format for Literal IPv6 Addresses in > URL's](https://www.ietf.org/rfc/rfc2732.html), [Uniform Resource Identifier > (URI): Generic Syntax](https://www.ietf.org/rfc/rfc3986.html), [Uniform > Resource Identifiers (URI): Generic > Syntax](https://www.ietf.org/rfc/rfc2396.html) > > You will see that two of the RFC links have the same text but link to > different RFCs, which I am finding confusing. Also I do hope it's clear that > if a specification is referenced it doesn't mean it's being implemented. On keeping RFC in the title, I'll go with the team preference. I note that not all spec authorities have such a well-defined naming/numbering scheme, so it does make the summary page a bit inconsistent. Also, the entries under "R" dominate the list, which may not be what you want. On the same text but linking to different RFCs: that's tantamount to a bug somewhere. The spec for `@spec` dictates that the URLs and titles should be in 1-1 correspondence, and this is supposed to be enforced in the docket. In other words, specs should have unique titles, and any title should only be used for one spec. - PR: https://git.openjdk.org/jdk/pull/11073
RFR: JDK-8296547: Add @spec tags to API
Please review a "somewhat automated" change to insert `@spec` tags into doc comments, as appropriate, to leverage the recent new javadoc feature to generate a new page listing the references to all external specifications listed in the `@spec` tags. "Somewhat automated" means that I wrote and used a temporary utility to scan doc comments looking for HTML links to selected sites, such as `ietf.org`, `unicode.org`, `w3.org`. These links may be in the main description of a doc comment, or in `@see` tags. For each link, the URL is examined, and "normalized", and inserted into the doc comment with a new `@spec` tag, giving the link and tile for the spec. "Normalized" means... * Use `https:` where possible (includes pretty much all cases) * Use a single consistent host name for all URLs coming from the same spec site (i.e. don't use different aliases for the same site) * Point to the root page of a multi-page spec * Use a consistent form of the spec, preferring HTML over plain text where both are available (this mostly applies to IETF specs) In addition, a "standard" title is determined for all specs, determined either from the content of the (main) spec page or from site index pages. The net effect is (or should be) that **all** the changes are to just **add** new `@spec` tags, based on the links found in each doc comment. There should be no other changes to the doc comments, or to the implementation of any classes and interfaces. That being said, the utility I wrote does have additional abilities, to update the links that it finds (e.g. changing to use `https:` etc,) but those features are _not_ being used here, but could be used in followup PRs if component teams so desired. I did notice while working on this overall feature that many of our links do point to "outdated" pages, some with eye-catching notices declaring that the spec has been superseded. Determining how, when and where to update such links is beyond the scope of this PR. Going forward, it is to be hoped that component teams will maintain the underlying links, and the URLs in `@spec` tags, such that if references to external specifications are updated, this will include updating the `@spec` tags. To see the effect of all these new `@spec` tags, see http://cr.openjdk.java.net/~jjg/8296546/api.00/ In particular, see the new [External Specifications](http://cr.openjdk.java.net/~jjg/8296546/api.00/external-specs.html) page, which you can also find via the new link near the top of the [Index](http://cr.openjdk.java.net/~jjg/8296546/api.00/index-files/index-1.html) pages. - Commit messages: - JDK-8296547: Add @spec tags to API Changes: https://git.openjdk.org/jdk/pull/11073/files Webrev: https://webrevs.openjdk.org/?repo=jdk&pr=11073&range=00 Issue: https://bugs.openjdk.org/browse/JDK-8296547 Stats: 816 lines in 420 files changed: 816 ins; 0 del; 0 mod Patch: https://git.openjdk.org/jdk/pull/11073.diff Fetch: git fetch https://git.openjdk.org/jdk pull/11073/head:pull/11073 PR: https://git.openjdk.org/jdk/pull/11073
Re: RFR: 8294241: Deprecate URL public constructors [v2]
On Fri, 28 Oct 2022 14:54:26 GMT, Daniel Fuchs wrote:
>> Deprecate URL constructors. Developers are encouraged to use `java.net.URI`
>> to parse or construct any URL.
>>
>> The `java.net.URL` class does not itself encode or decode any URL components
>> according to the escaping mechanism defined in RFC2396. It is the
>> responsibility of the caller to encode any fields, which need to be escaped
>> prior to calling URL, and also to decode any escaped fields, that are
>> returned from URL.
>>
>> This has lead to many issues in the past. Indeed, if used improperly, there
>> is no guarantee that `URL::toString` or `URL::toExternalForm` will lead to a
>> URL string that can be parsed back into the same URL. This can lead to
>> constructing misleading URLs. Another issue is with `equals()` and
>> `hashCode()` which may have to perform a lookup, and do not take
>> encoding/escaping into account.
>>
>> In Java SE 1.4 a new class, `java.net.URI`, has been added to mitigate some
>> of the shortcoming of `java.net.URL`. Conversion methods to create a URL
>> from a URI were also added. However, it was left up to the developers to use
>> `java.net.URI`, or not. This RFE proposes to deprecate all public
>> constructors of `java.net.URL`, in order to provide a stronger warning about
>> their potential misuses. To construct a URL, using `URI::toURL` should be
>> preferred.
>>
>> In order to provide an alternative to the constructors that take a stream
>> handler as parameter, a new factory method `URL::fromURI(java.net.URI,
>> java.net.URLStreamHandler)` is provided as part of this change.
>>
>> Places in the JDK code base that were constructing `java.net.URL` have been
>> temporarily annotated with `@SuppressWarnings("deprecation")`. Some related
>> issues will be logged to revisit the calling code.
>>
>> The CSR can be reviewed here: https://bugs.openjdk.org/browse/JDK-8295949
>
> Daniel Fuchs 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 four additional
> commits since the last revision:
>
> - Updated after review comments. In particular var tmp => var => _unused -
> and avoid var in java.xml
> - Merge branch 'master' into deprecate-url-ctor-8294241
> - Fix whitespace issues
> - 8294241
The changes in `jdk.compiler` and `jdk.javadoc` seem innocuous enough. Because
of the bootstrap issue/latency, we'll have to wait before we can update to
non-deprecated code.
-
PR: https://git.openjdk.org/jdk/pull/10874
Re: RFR: 8295729: Add jcheck whitespace checking for properties files [v3]
On Mon, 24 Oct 2022 19:21:07 GMT, Magnus Ihse Bursie wrote: >> Properties files is essentially source code. It should have the same >> whitespace checks as all other source code, so we don't get spurious >> trailing whitespace changes. >> >> With the new Skara jcheck, it is possible to increase the coverage of the >> whitespace checks (in the old mercurial version, this was more or less >> impossible). >> >> The only manual change is to `.jcheck/conf`. All other changes were made by >> running `find . -type f -iname "*.properties" | xargs gsed -i -e 's/[ >> \t]*$//'`. > > Magnus Ihse Bursie has updated the pull request incrementally with two > additional commits since the last revision: > > - Revert "Remove check for .properties from jcheck" > >This reverts commit c91fdaa19dc06351598bd1c0614e1af3bfa08ae2. > - Change trailing space and tab in values to unicode encoding I think it would be better to try and remove incidental trailing whitespace first, before encoding any remaining whitespace. Hiding the trailing whitespace as a Unicode escape seems like a bad idea, equivalent to sweeping the issue under the rug. While I agree with the goals of improving the check, I think this is going about it the wrong way, or at least in the wrong order. Maybe it would be a good idea to first validate the default/English files, checking for incidental whitespace there, then check localized versions of each property against the English version. - PR: https://git.openjdk.org/jdk/pull/10792
Re: [jdk19] RFR: 8278274: Update nroff pages in JDK 19 before RC
On Sun, 17 Jul 2022 22:44:02 GMT, David Holmes wrote: > Please review these changes to the nroff manpage files so that they match > their markdown sources that Oracle maintains. > > All pages at a minimum have 19-ea replaced with 19, and copyright set to 2022 > if needed. Additionally: > > The Java manpage was missing updates from: > - [JDK-8282018](https://bugs.openjdk.org/browse/JDK-8282018): Add captions to > tables on java man page. > > The Java manpage has slight formatting differences from: > - [JDK-8262004](https://bugs.openjdk.org/browse/JDK-8262004): Classpath > separator: Man page says semicolon; should be colon on Linux > - [JDK-8236569](https://bugs.openjdk.org/browse/JDK-8236569): -Xss not > multiple of 4K does not work for the main thread on macOS > > The Java manpage has a typo fixed in mainline by > [JDK-8279047](https://bugs.openjdk.org/browse/JDK-8279047) (for JDK 20) > > > The keytool manpage was missing updates from: > - [JDK-8282014](https://bugs.openjdk.org/browse/JDK-8282014): Add captions to > tables on keytool man page. > - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger > default key sizes and algorithms based on CNSA > > The jar manpage was missing updates from: > - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod > man pages need the new --date documenting from CSR > [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755) > > The jarsigner manpage was missing updates from: > - [JDK-8282015](https://bugs.openjdk.org/browse/JDK-8282015): Add captions to > tables on jarsigner man page. > - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger > default key sizes and algorithms based on CNSA > > The javadoc manpage was missing updates from: > - [JDK-8279034](https://bugs.openjdk.org/browse/JDK-8279034): Update man page > for javadoc `--date` option > > The jmod manpage was missing updates from: > - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod > man pages need the new --date documenting from CSR > [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755) > > The jpackage manpage was missing updates from: > - [JDK-8285146](https://bugs.openjdk.org/browse/JDK-8285146): Document > jpackage resource dir feature > - [JDK-8284695](https://bugs.openjdk.org/browse/JDK-8284695): Update jpackage > man pages for JDK 19 > - [JDK-8284209](https://bugs.openjdk.org/browse/JDK-8284209): Replace > remaining usages of 'a the' in source code > > The jshell manpage was missing updates from: > - [JDK-8282016](https://bugs.openjdk.org/browse/JDK-8282016): Add captions to > tables on jshell man page. The version changes in each file look good (`19-ea` to `19`). The changes for javadoc look good. I looked over the other changes for other files, and while they look good, I cannot speak for their technical accuracy. That being said, this is an automated process deriving info from upstream, so is likely OK. - Marked as reviewed by jjg (Reviewer). PR: https://git.openjdk.org/jdk19/pull/145
Re: [jdk19] RFR: 8278274: Update nroff pages in JDK 19 before RC
On Sun, 17 Jul 2022 22:44:02 GMT, David Holmes wrote: > Please review these changes to the nroff manpage files so that they match > their markdown sources that Oracle maintains. > > All pages at a minimum have 19-ea replaced with 19, and copyright set to 2022 > if needed. Additionally: > > The Java manpage was missing updates from: > - [JDK-8282018](https://bugs.openjdk.org/browse/JDK-8282018): Add captions to > tables on java man page. > > The Java manpage has slight formatting differences from: > - [JDK-8262004](https://bugs.openjdk.org/browse/JDK-8262004): Classpath > separator: Man page says semicolon; should be colon on Linux > - [JDK-8236569](https://bugs.openjdk.org/browse/JDK-8236569): -Xss not > multiple of 4K does not work for the main thread on macOS > > The Java manpage has a typo fixed in mainline by > [JDK-8279047](https://bugs.openjdk.org/browse/JDK-8279047) (for JDK 20) > > > The keytool manpage was missing updates from: > - [JDK-8282014](https://bugs.openjdk.org/browse/JDK-8282014): Add captions to > tables on keytool man page. > - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger > default key sizes and algorithms based on CNSA > > The jar manpage was missing updates from: > - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod > man pages need the new --date documenting from CSR > [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755) > > The jarsigner manpage was missing updates from: > - [JDK-8282015](https://bugs.openjdk.org/browse/JDK-8282015): Add captions to > tables on jarsigner man page. > - [JDK-8267319](https://bugs.openjdk.org/browse/JDK-8267319): Use larger > default key sizes and algorithms based on CNSA > > The javadoc manpage was missing updates from: > - [JDK-8279034](https://bugs.openjdk.org/browse/JDK-8279034): Update man page > for javadoc `--date` option > > The jmod manpage was missing updates from: > - [JDK-8278764](https://bugs.openjdk.org/browse/JDK-8278764): jar and jmod > man pages need the new --date documenting from CSR > [JDK-8277755](https://bugs.openjdk.org/browse/JDK-8277755) > > The jpackage manpage was missing updates from: > - [JDK-8285146](https://bugs.openjdk.org/browse/JDK-8285146): Document > jpackage resource dir feature > - [JDK-8284695](https://bugs.openjdk.org/browse/JDK-8284695): Update jpackage > man pages for JDK 19 > - [JDK-8284209](https://bugs.openjdk.org/browse/JDK-8284209): Replace > remaining usages of 'a the' in source code > > The jshell manpage was missing updates from: > - [JDK-8282016](https://bugs.openjdk.org/browse/JDK-8282016): Add captions to > tables on jshell man page. src/java.base/share/man/keytool.1 line 456: > 454: \f[CB]PrivateKeyEntry\f[R] for the signer that already exists in the > 455: keystore. > 456: This option is used to sign the certificate with the signer?s private Not a problem with this PR as such, but we still have a `?` character in the output. - PR: https://git.openjdk.org/jdk19/pull/145
