Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

8250590: Classes and methods in the javafx.css package are missing documentation #589

Closed
wants to merge 6 commits into from

Conversation

aghaisas
Copy link
Collaborator

@aghaisas aghaisas commented Jul 26, 2021

This PR corrects/adds missing documentation for classes in javafx.css package.


Progress

  • Change must not contain extraneous whitespace
  • Commit message must refer to an issue
  • Change must be properly reviewed

Issue

  • JDK-8250590: Classes and methods in the javafx.css package are missing documentation

Reviewers

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.java.net/jfx pull/589/head:pull/589
$ git checkout pull/589

Update a local copy of the PR:
$ git checkout pull/589
$ git pull https://git.openjdk.java.net/jfx pull/589/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 589

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

Using diff file

Download this PR as a diff file:
https://git.openjdk.java.net/jfx/pull/589.diff

Sorry, something went wrong.

@bridgekeeper
Copy link

bridgekeeper bot commented Jul 26, 2021

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

@openjdk openjdk bot added the rfr Ready for review label Jul 26, 2021
@mlbridge
Copy link

mlbridge bot commented Jul 26, 2021

Webrevs

Copy link
Member

@kevinrushforth kevinrushforth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I applied the patch and confirm that there are no more "missing comments" warnings for the javafx.css package.

The docs look reasonable in general. I did note a few examples of usage patterns that should be fixed globally. Most of these fell into the following general categories.

  1. The body of the javadoc comments for a class, method, etc., should be one or more complete sentences starting with a capital letter and ending with a period.
  2. The text following @return and @param typically starts with a lower-case letter and does not end with a period.
  3. When referring to a class name, method name, or formal parameter name, we usually use {@code ... } style or else separate words that are all lower-case. For example, either {@code ParsedValue} or parsed value is fine (but not ParsedValue).

In addition to noting one or two examples of each of the above, I left a few random inline comments.

@kevinrushforth
Copy link
Member

A second pair of eyes would be good for these changes.

/reviewers 2

@openjdk
Copy link

openjdk bot commented Jul 26, 2021

@kevinrushforth
The number of required reviews for this PR is now set to 2 (with at least 1 of role reviewers).

@nlisker
Copy link
Collaborator

nlisker commented Jul 28, 2021

I have spotted some missing docs:

  • CompoundSelector missing docs for methods overriden from Object.
  • CssMetaData is missing docs for methods hashCode(), getConverter() and getProperty().
  • CssParser.ParseError for toString().

I stopped checking at this point. It seems that the the script warning for missing docs isn't looking at overriden methods. getProperty() and getConverter() were not caught since they have an @return doc, but no method summary.

@pankaj-bansal
Copy link
Collaborator

pankaj-bansal commented Jul 28, 2021

I understand we discussed this in the meeting, but I am surprised that this does not need a CSR. It looks like too much bigger documentation change for not needing a CSR. Besides this, I have given some minor comments, otherwise it looks fine to me.

@kevinrushforth
Copy link
Member

I am surprised that this does not need a CSR. It looks like too much bigger documentation change for not needing a CSR.

JavaFX doesn't impose the same requirement of needing a CSR for everything that touches API documentation as does the JDK. In this case, it is just adding obvious and missing API docs without any changes in documented behavior or any additional conditions in the specification. While it wouldn't hurt to have a CSR, I'm not sure I see the need.

Btw, the number of lines of documentation added isn't really the question. A one-line change can end up needing a CSR if there are changes to the specified semantics.

@kevinrushforth
Copy link
Member

I have spotted some missing docs:

  • CompoundSelector missing docs for methods overriden from Object.

I'm not too worried about the missing docs for overridden methods. Unless we are overriding it in a way that needs to be documented, we don't want or need to add any explicit documentation. We could add /** {@inheritDoc} */ for those (and it seems a good idea), but it turns out that when overriding JDK methods such as toString(), the generated docs are the same with or without {@inheritDoc}. We could consider a follow-on issue (not limited to javafx.css) to address this, which might involve changes to options that we pass to the javadoc tool.

  • CssMetaData is missing docs for methods hashCode(), getConverter() and getProperty().

I think getProperty() and getConverter() should be fixed in this PR.

@nlisker
Copy link
Collaborator

nlisker commented Jul 28, 2021

I think getProperty() and getConverter() should be fixed in this PR.

There could be more methods like that. Maybe the script should check specifically for a missing summary?

Copy link
Member

@kevinrushforth kevinrushforth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did a pretty complete review of the docs, and left what are mostly minor (and in some cases picky) comments.

@kevinrushforth
Copy link
Member

I think getProperty() and getConverter() should be fixed in this PR.

There could be more methods like that. Maybe the script should check specifically for a missing summary?

We just used the javadoc tool to find them, so would need support from the javadoc tool itself. I looked through all of the docs and only found one more: ParsedValue.getValue().

@aghaisas
Copy link
Collaborator Author

aghaisas commented Jul 29, 2021

I think getProperty() and getConverter() should be fixed in this PR.

There could be more methods like that. Maybe the script should check specifically for a missing summary?

We just used the javadoc tool to find them, so would need support from the javadoc tool itself. I looked through all of the docs and only found one more: ParsedValue.getValue().

I found few more such methods in javafx.css package using "find in files" in my editor and fixed them.

  • CssMetaData.getProperty()
  • CssMetaData.getConverter()
  • ParsedValue.getValue()
  • PseudoClassImpl.getPseudoClassName()
  • PseudoClassImpl.toString()
  • SimpleSelector.getPseudoclasses()

Interestingly, this is not only limited to javafx.css package, but spread across all JavaFX modules.
I have filed JDK-8271460 for fixing this.

@aghaisas
Copy link
Collaborator Author

Thanks for a detailed review of the changes.
I have addressed the review comments. Request your re-look at the latest changes.

@nlisker
Copy link
Collaborator

nlisker commented Jul 29, 2021

In Declaration something is wrong with the html rendering in the last lines, the columns are misaligned:
image

Same with Stylesheet.

Does it comes out like that just for me? I didn't see anything wrong with the code after a quick look.

Also, Match.compareTo is overriden from Comparable<Match> without a doc, but maybe something needs to be specified there about what is being compared or for what purpose Comparable is implemented to begin with?

@aghaisas
Copy link
Collaborator Author

I see that this is a much wider problem with openjfx17 documentation.
Wherever only @inheritDoc is used, we are having this corruption in final html documentation.
For example - look for class documentation of javafx.scene.layout.BackgroundSize in html.
The same class documentation of openjfx16 is all fine - (https://openjfx.io/javadoc/16/javafx.graphics/javafx/scene/layout/BackgroundSize.html)

Need to find root cause and fix this.

@kevinrushforth
Copy link
Member

Wherever only @inheritdoc is used, we are having this corruption in final html documentation

I saw this problem with @inheritDoc yesterday as well, and was getting ready to report it here, but then couldn't reproduce it with a clean build of the docs. I'll try it again with a fully clean build (not just a clean docs build). If reproducible, it seems likely that this is a bug in the javadoc tool.

@kevinrushforth
Copy link
Member

I found few more such methods in javafx.css package using "find in files" in my editor and fixed them.

...

  • PseudoClassImpl.getPseudoClassName()
  • PseudoClassImpl.toString()
  • SimpleSelector.getPseudoclasses()

These three are not part of the public API. PseudoClassImpl is a package-scope class and SimpleSelector.getPseudoclasses() is a package-scope method, so they don't need any javadoc comments (although since you've already added them, there is no need to remove them).

@kevinrushforth
Copy link
Member

Wherever only @inheritdoc is used, we are having this corruption in final html documentation

I saw this problem with @inheritDoc yesterday as well, and was getting ready to report it here, but then couldn't reproduce it with a clean build of the docs. I'll try it again with a fully clean build (not just a clean docs build). If reproducible, it seems likely that this is a bug in the javadoc tool.

I can confirm that this is a javadoc tool bug. It is already fixed in JDK 17, but since we use JDK 16 as the boot JDK, we will see it. Since {@inheritDoc} doesn't do anything for standard JDK classes that we override, except to provoke this bug, we should avoid this pattern for now.

Copy link
Member

@kevinrushforth kevinrushforth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I left just a few more (mostly minor) comments.

@aghaisas
Copy link
Collaborator Author

aghaisas commented Jul 29, 2021

Also, Match.compareTo is overriden from Comparable without a doc, but maybe something needs to be specified there about what is being compared or for what purpose Comparable is implemented to begin with?

I will add the documentation for this method.

@aghaisas
Copy link
Collaborator Author

Wherever only @inheritdoc is used, we are having this corruption in final html documentation

I saw this problem with @inheritDoc yesterday as well, and was getting ready to report it here, but then couldn't reproduce it with a clean build of the docs. I'll try it again with a fully clean build (not just a clean docs build). If reproducible, it seems likely that this is a bug in the javadoc tool.

I can confirm that this is a javadoc tool bug. It is already fixed in JDK 17, but since we use JDK 16 as the boot JDK, we will see it. Since {@inheritDoc} doesn't do anything for standard JDK classes that we override, except to provoke this bug, we should avoid this pattern for now.

I have filed JDK-8271485 to address this.

@kevinrushforth
Copy link
Member

I have filed JDK-8271485 to address this.

I just submitted PR #593 with a fix. It will also address the problem noted above of overridden methods without additional documentation showing up with no description, since such methods will no longer show up in the first place.

Copy link
Member

@kevinrushforth kevinrushforth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two remaining comments. I looked through all the generated docs and everything else looks good.

Copy link
Member

@kevinrushforth kevinrushforth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good!

Copy link
Collaborator

@pankaj-bansal pankaj-bansal left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me as well

@openjdk
Copy link

openjdk bot commented Jul 30, 2021

@aghaisas 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:

8250590: Classes and methods in the javafx.css package are missing documentation

Reviewed-by: kcr, pbansal

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 5 new commits pushed to the jfx17 branch:

  • df07ac8: 8212088: Missing copyright notices for property files
  • 78a3721: 8271086: Block comments of form '/***' are treated as javadoc comments
  • 2cd5d1f: 8240640: [macos] Wrong focus behaviour with multiple Alerts
  • 0e5b788: 8271230: Remove obsolete test classes and data files from 3DViewer sample
  • d540109: 8270959: Update boot JDK to 16.0.2

Please see this link for an up-to-date comparison between the source branch of this pull request and the jfx17 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 jfx17 branch, type /integrate in a new comment.

@openjdk openjdk bot added the ready Ready to be integrated label Jul 30, 2021
@aghaisas
Copy link
Collaborator Author

aghaisas commented Aug 3, 2021

/integrate

@openjdk
Copy link

openjdk bot commented Aug 3, 2021

Going to push as commit 7575473.
Since your change was applied there have been 5 commits pushed to the jfx17 branch:

  • df07ac8: 8212088: Missing copyright notices for property files
  • 78a3721: 8271086: Block comments of form '/***' are treated as javadoc comments
  • 2cd5d1f: 8240640: [macos] Wrong focus behaviour with multiple Alerts
  • 0e5b788: 8271230: Remove obsolete test classes and data files from 3DViewer sample
  • d540109: 8270959: Update boot JDK to 16.0.2

Your commit was automatically rebased without conflicts.

@openjdk openjdk bot closed this Aug 3, 2021
@openjdk openjdk bot added integrated Pull request has been integrated and removed ready Ready to be integrated rfr Ready for review labels Aug 3, 2021
@openjdk
Copy link

openjdk bot commented Aug 3, 2021

@aghaisas Pushed as commit 7575473.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
integrated Pull request has been integrated
Development

Successfully merging this pull request may close these issues.

None yet

4 participants