Re: RFR: 8271090: Missing API docs in scenegraph classes [v2]
On Mon, 25 Oct 2021 23:27:19 GMT, Kevin Rushforth wrote: > Looks good with a couple suggestions on `setScene`. We might want to also > file a follow-up javadoc bug so we can get rid of the javadocs for that > method altogether. I have filed - [JDK-8275910](https://bugs.openjdk.java.net/browse/JDK-8275910) for this. - PR: https://git.openjdk.java.net/jfx/pull/650
Re: RFR: 8271090: Missing API docs in scenegraph classes [v2]
On Mon, 25 Oct 2021 08:30:36 GMT, Ajit Ghaisas wrote:
>> This PR fixes javadoc warnings primarily in javafx.graphics module along
>> with a remaining few in javafx.fxml, javafx.base and javafx.media modules.
>>
>> Note :
>> - The javadoc needs to be generated with the JDK 18 EA build.
>> - There are still few remaining warnings in these modules. The root cause is
>> different and they will be addressed under
>> [JDK-8270996](https://bugs.openjdk.java.net/browse/JDK-8270996)
>
> Ajit Ghaisas has updated the pull request incrementally with one additional
> commit since the last revision:
>
> 8271090 - fix review comments
Looks good with a couple suggestions on `setScene`. We might want to also file
a follow-up javadoc bug so we can get rid of the javadocs for that method
altogether.
modules/javafx.graphics/src/main/java/javafx/stage/Window.java line 781:
> 779: * Sets the value of the {@code scene} property.
> 780: *
> 781: * The {@code Scene} to be rendered on this {@code Window}. There
> can only
Can you add a `` tag here? This will be closer to what an
implicitly-generated setter would do.
modules/javafx.graphics/src/main/java/javafx/stage/Window.java line 798:
> 796: * @defaultValue null
> 797: *
> 798: * @param value the value for the {@code scene} property
Can you add the following tags?
`@see getScene()`
`@see sceneProperty()`
-
PR: https://git.openjdk.java.net/jfx/pull/650
Re: RFR: 8271090: Missing API docs in scenegraph classes [v2]
On Fri, 22 Oct 2021 15:00:58 GMT, Kevin Rushforth wrote:
>> Ajit Ghaisas has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> 8271090 - fix review comments
>
> modules/javafx.graphics/src/main/java/javafx/stage/Window.java line 781:
>
>> 779: * Sets the {@code Scene} of this {@code Window}.
>> 780: * @param value the {@code Scene} to be set
>> 781: */
>
> The javadoc tool automatically generates docs for this setter (you can see
> this from the generated docs without this change), including the property
> description, so this change will actually lose information. I'm guessing that
> the tool warns on this method because the setter is protected (rather than
> public). So we should probably file a bug against the javadoc tool. As for
> how to fix it, you can either suppress the warning (I'm not sure whether
> that's possible), or you can copy the information from the property method
> with a leading sentence that matches what javadoc _would_ generate.
Suppressing this warning is logical - but not possible.
As suggested, I have copied the property information and added the set method
description that was generated by javadoc tool before this fix.
-
PR: https://git.openjdk.java.net/jfx/pull/650
Re: RFR: 8271090: Missing API docs in scenegraph classes [v2]
On Fri, 22 Oct 2021 15:30:36 GMT, Kevin Rushforth wrote:
>> modules/javafx.graphics/src/main/java/javafx/scene/shape/Box.java line 91:
>>
>>> 89: * Default size of the {@code Box}.
>>> 90: */
>>> 91: public static final double DEFAULT_SIZE = 2;
>>
>> This field was exposed by mistake probably. The other shapes don't expose
>> theirs. I recommend to deprecate for removal.
>
> Agreed. That would need to be done in a follow-up issue, and with a CSR. So
> just revert this addition for this PR.
Reverted this change.
Filed [JDK-8275848](https://bugs.openjdk.java.net/browse/JDK-8275848) for
addressing this.
-
PR: https://git.openjdk.java.net/jfx/pull/650
Re: RFR: 8271090: Missing API docs in scenegraph classes [v2]
On Fri, 22 Oct 2021 14:37:14 GMT, Nir Lisker wrote:
>> Ajit Ghaisas has updated the pull request incrementally with one additional
>> commit since the last revision:
>>
>> 8271090 - fix review comments
>
> modules/javafx.media/src/main/java/javafx/scene/media/Track.java line 85:
>
>> 83: /**
>> 84: * Gets the Map containing all known metadata for this
>> Track.
>> 85: * @return the Map containing all known metadata for
>> this Track
>
> We tend to use `{@code }` over ` `, but I don't think it matter.
I have just maintained the local convention used in this file.
-
PR: https://git.openjdk.java.net/jfx/pull/650
Re: RFR: 8271090: Missing API docs in scenegraph classes [v2]
> This PR fixes javadoc warnings primarily in javafx.graphics module along with > a remaining few in javafx.fxml, javafx.base and javafx.media modules. > > Note : > - The javadoc needs to be generated with the JDK 18 EA build. > - There are still few remaining warnings in these modules. The root cause is > different and they will be addressed under > [JDK-8270996](https://bugs.openjdk.java.net/browse/JDK-8270996) Ajit Ghaisas has updated the pull request incrementally with one additional commit since the last revision: 8271090 - fix review comments - Changes: - all: https://git.openjdk.java.net/jfx/pull/650/files - new: https://git.openjdk.java.net/jfx/pull/650/files/239c0634..9ff692db Webrevs: - full: https://webrevs.openjdk.java.net/?repo=jfx=650=01 - incr: https://webrevs.openjdk.java.net/?repo=jfx=650=00-01 Stats: 38 lines in 6 files changed: 21 ins; 12 del; 5 mod Patch: https://git.openjdk.java.net/jfx/pull/650.diff Fetch: git fetch https://git.openjdk.java.net/jfx pull/650/head:pull/650 PR: https://git.openjdk.java.net/jfx/pull/650
