8341907: javac -Xlint should ignore /// on first line of source file #21923

pavelrappo · 2024-11-06T11:31:02Z

Please review this PR to exempt the trick that JBang uses from the "dangling comment" lint introduced in JDK 23. For more information see this PR's JBS issue and its comment section.

The fix makes sure that the warning is not issued if it relates to a leading /// comment. For simplicity and similarity with the shebang construct, the comment should start from the first character of the file, and not a more permissive first non-whitespace character of the file.

Since I'm not an expert in java.compiler, I'm unsure if my code intercepts warning in the most appropriate layer. Please double-check that.

Skimming through the tests which I used for inspiration, test/langtools/tools/javac/danglingDocComments, I was unsure why they compile itself first without any /ref= construct. The test I introduced here does not do this; am I missing something?

Progress

Change must be properly reviewed (1 review required, with at least 1 Reviewer)
Change must not contain extraneous whitespace
Commit message must refer to an issue

Warning

⚠️ Found leading lowercase letter in issue title for 8341907: javac -Xlint should ignore /// on first line of source file

Issue

JDK-8341907: javac -Xlint should ignore /// on first line of source file (Bug - P4)

Reviewers

Jonathan Gibbons (@jonathan-gibbons - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/21923/head:pull/21923
$ git checkout pull/21923

Update a local copy of the PR:
$ git checkout pull/21923
$ git pull https://git.openjdk.org/jdk.git pull/21923/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 21923

View PR using the GUI difftool:
$ git pr show -t 21923

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/21923.diff

Using Webrev

Link to Webrev Comment

bridgekeeper · 2024-11-06T11:31:35Z

👋 Welcome back prappo! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

openjdk · 2024-11-06T11:32:20Z

@pavelrappo This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8341907: javac -Xlint should ignore /// on first line of source file

Reviewed-by: jjg

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 2 new commits pushed to the master branch:

133f8f3: 8344014: Simplify TracePhase constructor
d334af0: 8344089: Fix wrong location of TestWrongMinLWiden.java

Please see this link for an up-to-date comparison between the source branch of this pull request and the master branch.
As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

openjdk · 2024-11-06T11:33:13Z

@pavelrappo The following label will be automatically applied to this pull request:

compiler

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing list. If you would like to change these labels, use the /label pull request command.

mlbridge · 2024-11-06T11:36:01Z

Webrevs

jonathan-gibbons · 2024-11-06T21:04:24Z

test/langtools/tools/javac/danglingDocComments/JBangExceptionTest.java

+// otherwise interfere with the JTReg test comment. For similar reasons,
+// the files with test classes do __NOT__ have a copyright header.


FYI, the normal guidance for source files that cannot follow standard stylistic guidance (such as files with tabs etc) is to dynamically generate the files, which is medium easy these days using text blocks. That being said, that advice does not work well in this case because the jtreg infrastructure for @compile tags does not work for generated files.

In this case, I would recommend working the text string nodynamiccopyright into the head of the two JBang files. There are two or three possibilities.

Just put the word nodynamiccopyright at the end of the first line. Syntactically, it would be a command name, but such a command would never be executed after the exit statement.

Put a comment #nodynamiccopyright at the end of the first line.

Put a separate Java comment on the second line, using either an end-of-line comment or traditional comment. It might then be reasonably detected and taken into account by any automated scripts that ensure copyright headers are present unless that keyword is present.

Number 3 seems to be the cleanest. I'll try it; thanks.

OK, but since we're not testing the files here with JBang, all that matters is the recognition of the overall comment, regardless of its content. But #3 is OK too. The main thing is to have the keyword present so that any checkers scripts have explicit evidence that no comment is intended in these files.

jonathan-gibbons · 2024-11-06T21:06:46Z

src/jdk.compiler/share/classes/com/sun/tools/javac/parser/JavacParser.java

+                if (lint.isEnabled(Lint.LintCategory.DANGLING_DOC_COMMENTS) &&
+                        (c.getStyle() != Comment.CommentStyle.JAVADOC_LINE ||
+                                c.getPos().getStartPosition() != 0)) {


For consideration, you could further refine the test by making sure it is a single line comment (perhaps optionally terminated by a newline). In other words, maybe the warning should be given if the leading comment is a multi-line comment -- which would unlikely be a JBang-style comment.

I admit, I thought about it initially, but couldn't quickly come up with a simple and robust way to figure out if a comment tree spans a single line. I'm not yet comfortable working with compiler coordinate system (incl. source positions). If you propose such a way, I'd happily incorporate it.

If you propose such a way, I'd happily incorporate it.

Does the content of the comment (c.getText()) contain a newline character that is not at the end of the content? Maybe something like
c.getText().matches("(?s)\\R.")
although there may be more effective ways to do that.

Regex sounds simple and robust. However, I thought we could concoct a more idiomatic compiler solution, using trees, start and end diagnostic positions, and also line numbers.

So, if a comment tree start and end position are on the same line that is also the first line of the file, we don't output the warning. Can we do that?

Computing line numbers is a relatively expensive operation, because the internal coordinates are character-offset based. That being said, there is a bunch of caching going on under the covers, and, the check can be guarded by the additional (proposed) check that the warning is only suppressed if the comment begins at offset 0.

Generally, the method you want is DiagnosticSource.getLineNumber(int pos), which means you need a DiagnosticSource object. JavacParser (that is, this class) has a Log log member, and [Abstract]Log provides currentSource(), so to get the line number for a position it should be possible to use something like log.currentSource().getLineNumber(pos), assuming that the current source is set up correctly at the time you need it.

So, if a comment tree start and end position are on the same line that is also the first line of the file

The end position will always be after the start position, so you only need check if the line number of the end position of the comment is line 1. (Line numbers are 1-based.)

Jon, please have a look at the updated version and approve if it is to your liking; thanks.

jonathan-gibbons · 2024-11-06T21:10:57Z

I was unsure why they compile itself first without any /ref= construct.

My recollection is that this just a convenience to get the output of the compilation into the log without any /ref analysis, for the situations where the test in invalid and fails to compile.

pavelrappo · 2024-11-15T10:19:39Z

/integrate

openjdk · 2024-11-15T10:20:13Z

Going to push as commit 3eece6e.
Since your change was applied there have been 64 commits pushed to the master branch:

5b9932f: 8338288: Compiler Implementation for Flexible Constructor Bodies (Third Preview)
0c191f6: 8344185: Remove calls to SecurityManager in sun.net.ftp
bfee766: 8344183: (zipfs) SecurityManager cleanup in the ZipFS area
857f68c: 8344179: SecurityManager cleanup in the ZIP and JAR areas
2196694: 8344104: TestMergeStores fails with ArrayIndexOutOfBoundException
0ae5748: 8343982: Remove usage of security manager from ClassLoader and related classes
9907065: 8344065: Remove SecurityManager uses from the java.datatransfer module
db56266: 8344250: Obsolete the DontYieldALot flag
7ef2633: 8344128: Regression: make help broken after JDK-8340818
d959c7d: 8344147: Remove Security Manager dependencies from java.security.sasl module
... and 54 more: https://git.openjdk.org/jdk/compare/79345bbbae2564f9f523859d1227a1784293b20f...master

Your commit was automatically rebased without conflicts.

openjdk · 2024-11-15T10:20:23Z

@pavelrappo Pushed as commit 3eece6e.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

Initial commit

2134396

openjdk bot added the rfr Pull request is ready for review label Nov 6, 2024

openjdk bot added the compiler [email protected] label Nov 6, 2024

jonathan-gibbons reviewed Nov 6, 2024

View reviewed changes

Pavel Rappo added 3 commits November 6, 2024 23:36

Address copyright issues

cc9a379

Make the check more specific

558eb24

Fix a pre-existing doc typo

65ba8dc

jonathan-gibbons approved these changes Nov 8, 2024

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Nov 8, 2024

Merge branch 'master' into 8341907

e57eb6e

openjdk bot added the integrated Pull request has been integrated label Nov 15, 2024

openjdk bot closed this Nov 15, 2024

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Nov 15, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

8341907: javac -Xlint should ignore /// on first line of source file #21923

8341907: javac -Xlint should ignore /// on first line of source file #21923

pavelrappo commented Nov 6, 2024 •

edited by openjdk bot

Loading

bridgekeeper bot commented Nov 6, 2024

openjdk bot commented Nov 6, 2024 •

edited

Loading

openjdk bot commented Nov 6, 2024

mlbridge bot commented Nov 6, 2024 •

edited

Loading

jonathan-gibbons Nov 6, 2024 •

edited

Loading

pavelrappo Nov 6, 2024

jonathan-gibbons Nov 6, 2024

jonathan-gibbons Nov 6, 2024

pavelrappo Nov 6, 2024

jonathan-gibbons Nov 7, 2024 •

edited

Loading

pavelrappo Nov 7, 2024

jonathan-gibbons Nov 7, 2024 •

edited

Loading

jonathan-gibbons Nov 7, 2024

jonathan-gibbons Nov 7, 2024

pavelrappo Nov 8, 2024

jonathan-gibbons commented Nov 6, 2024

pavelrappo commented Nov 15, 2024

openjdk bot commented Nov 15, 2024

openjdk bot commented Nov 15, 2024

		// otherwise interfere with the JTReg test comment. For similar reasons,
		// the files with test classes do __NOT__ have a copyright header.

8341907: javac -Xlint should ignore /// on first line of source file #21923

8341907: javac -Xlint should ignore /// on first line of source file #21923

Conversation

pavelrappo commented Nov 6, 2024 • edited by openjdk bot Loading

Progress

Warning

Issue

Reviewers

Reviewing

bridgekeeper bot commented Nov 6, 2024

openjdk bot commented Nov 6, 2024 • edited Loading

openjdk bot commented Nov 6, 2024

mlbridge bot commented Nov 6, 2024 • edited Loading

Webrevs

jonathan-gibbons Nov 6, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan-gibbons Nov 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan-gibbons Nov 7, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jonathan-gibbons commented Nov 6, 2024

pavelrappo commented Nov 15, 2024

openjdk bot commented Nov 15, 2024

openjdk bot commented Nov 15, 2024

pavelrappo commented Nov 6, 2024 •

edited by openjdk bot

Loading

openjdk bot commented Nov 6, 2024 •

edited

Loading

mlbridge bot commented Nov 6, 2024 •

edited

Loading

jonathan-gibbons Nov 6, 2024 •

edited

Loading

jonathan-gibbons Nov 7, 2024 •

edited

Loading

jonathan-gibbons Nov 7, 2024 •

edited

Loading