<Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

classic Classic list List threaded Threaded
30 messages Options
12
Reply | Threaded
Open this post in threaded view
|

<Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Prasanta Sadhukhan-2
A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
has no spec.
Added spec for the method.

-------------

Commit messages:
 - 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Changes: https://git.openjdk.java.net/jdk/pull/3213/files
 Webrev: https://webrevs.openjdk.java.net/?repo=jdk&pr=3213&range=00
  Issue: https://bugs.openjdk.java.net/browse/JDK-8264218
  Stats: 12 lines in 1 file changed: 12 ins; 0 del; 0 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3213.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3213/head:pull/3213

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Sergey Bylokhov-2
On Fri, 26 Mar 2021 11:30:35 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
> has no spec.
> Added spec for the method.

Looks like the JavaDoc bug, the spec was there in jdk7:
https://docs.oracle.com/javase/7/docs/api/javax/swing/JMenu.html#setComponentOrientation(java.awt.ComponentOrientation)

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Prasanta Sadhukhan-2
On Sat, 27 Mar 2021 01:20:45 GMT, Sergey Bylokhov <[hidden email]> wrote:

>> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
>> has no spec.
>> Added spec for the method.
>
> Looks like the JavaDoc bug, the spec was there in jdk7:
> https://docs.oracle.com/javase/7/docs/api/javax/swing/JMenu.html#setComponentOrientation(java.awt.ComponentOrientation)

I could not see the spec in the last 14 years openjdk history of this file. Shouldn't we need to add the spec even if it's javadoc bug?
Instead of blindly copying JComponent setComponentOrientation spec as was done in jdk7 in above link, I have added a concise javadoc (same as is seen in JScrollPane#setComponentOrientation)

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Alexey Ivanov-2
On Thu, 1 Apr 2021 11:26:55 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

>> Looks like the JavaDoc bug, the spec was there in jdk7:
>> https://docs.oracle.com/javase/7/docs/api/javax/swing/JMenu.html#setComponentOrientation(java.awt.ComponentOrientation)
>
> I could not see the spec in the last 14 years openjdk history of this file. Shouldn't we need to add the spec even if it's javadoc bug?
> Instead of blindly copying JComponent setComponentOrientation spec as was done in jdk7 in above link, I have added a concise javadoc (same as is seen in JScrollPane#setComponentOrientation)

The method is also present in the Java 8:
https://docs.oracle.com/javase/8/docs/api/javax/swing/JMenu.html#setComponentOrientation-java.awt.ComponentOrientation-

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Prasanta Sadhukhan-2
On Thu, 1 Apr 2021 12:35:21 GMT, Alexey Ivanov <[hidden email]> wrote:

>> I could not see the spec in the last 14 years openjdk history of this file. Shouldn't we need to add the spec even if it's javadoc bug?
>> Instead of blindly copying JComponent setComponentOrientation spec as was done in jdk7 in above link, I have added a concise javadoc (same as is seen in JScrollPane#setComponentOrientation)
>
> The method is also present in the Java 8:
> https://docs.oracle.com/javase/8/docs/api/javax/swing/JMenu.html#setComponentOrientation-java.awt.ComponentOrientation-

I guess openjdk shows file history from 7u23 onwards IIRC so not sure why it is showing "Initial load" and not who/what removed it. Maybe the spec wordings actually was not there but some javadoc trickery was adding the javadoc comment in to the spec document seeing it's overidden from JComponent....
I am not sure what needs to be done here...

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Kevin Rushforth-2
On Thu, 1 Apr 2021 12:41:14 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

>> The method is also present in the Java 8:
>> https://docs.oracle.com/javase/8/docs/api/javax/swing/JMenu.html#setComponentOrientation-java.awt.ComponentOrientation-
>
> I guess openjdk shows file history from 7u23 onwards IIRC so not sure why it is showing "Initial load" and not who/what removed it. Maybe the spec wordings actually was not there but some javadoc trickery was adding the javadoc comment in to the spec document seeing it's overidden from JComponent....
> I am not sure what needs to be done here...

The `javadoc` tool (or the standard doclet) used to automatically copy the description from the superclass, and it seems that it no longer does. Perhaps @jonathan-gibbons could comment on this change?

@prsadhuk You could always add `@inheritDoc` like this:

/**
 * {@inheritDoc}
 */

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Alexey Ivanov-2
In reply to this post by Prasanta Sadhukhan-2
On Fri, 26 Mar 2021 11:30:35 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
> has no spec.
> Added spec for the method.

src/java.desktop/share/classes/javax/swing/JMenu.java line 1269:

> 1267:      * </ul>
> 1268:      * @see java.awt.ComponentOrientation
> 1269:      */

Shall it just use `{@inheritDoc}`?
The javadoc generated in 7 and 8 does exactly this.

However, the new text explicitly mentions that this method changes not only orientation of this component but also of the associated popup menu.

I do not think the description of the parameter has to list all the values of `ComponentOrientation`, these are the only publicly available values any way. If a value is added in the future, the javadoc will become incorrect.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Prasanta Sadhukhan-2
On Thu, 1 Apr 2021 12:42:19 GMT, Alexey Ivanov <[hidden email]> wrote:

>> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
>> has no spec.
>> Added spec for the method.
>
> src/java.desktop/share/classes/javax/swing/JMenu.java line 1269:
>
>> 1267:      * </ul>
>> 1268:      * @see java.awt.ComponentOrientation
>> 1269:      */
>
> Shall it just use `{@inheritDoc}`?
> The javadoc generated in 7 and 8 does exactly this.
>
> However, the new text explicitly mentions that this method changes not only orientation of this component but also of the associated popup menu.
>
> I do not think the description of the parameter has to list all the values of `ComponentOrientation`, these are the only publicly available values any way. If a value is added in the future, the javadoc will become incorrect.

It is done similarly in JScrollPane which I used here...maybe there also it's an oversight then..
I will update to use @inheritdoc in this spec ...

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec [v2]

Prasanta Sadhukhan-2
In reply to this post by Prasanta Sadhukhan-2
> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
> has no spec.
> Added spec for the method.

Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:

  Add @inheritDoc

-------------

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3213/files
  - new: https://git.openjdk.java.net/jdk/pull/3213/files/41eddf23..e2f1d259

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=3213&range=01
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=3213&range=00-01

  Stats: 10 lines in 1 file changed: 0 ins; 9 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3213.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3213/head:pull/3213

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec [v2]

Alexey Ivanov-2
In reply to this post by Prasanta Sadhukhan-2
On Thu, 1 Apr 2021 12:49:06 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

>> src/java.desktop/share/classes/javax/swing/JMenu.java line 1269:
>>
>>> 1267:      * </ul>
>>> 1268:      * @see java.awt.ComponentOrientation
>>> 1269:      */
>>
>> Shall it just use `{@inheritDoc}`?
>> The javadoc generated in 7 and 8 does exactly this.
>>
>> However, the new text explicitly mentions that this method changes not only orientation of this component but also of the associated popup menu.
>>
>> I do not think the description of the parameter has to list all the values of `ComponentOrientation`, these are the only publicly available values any way. If a value is added in the future, the javadoc will become incorrect.
>
> It is done similarly in JScrollPane which I used here...maybe there also it's an oversight then..
> I will update to use @inheritdoc in this spec ...

Yes, I see… Yet I think listing values of `ComponentOrientation` is redundant.

However, looking at JScrollPane, its javadoc specifies why it's overridden: _Sets the orientation for the vertical and horizontal scrollbars_. In the case of `JMenu`, it also changes the orientation of *popup menu* inside JMenu. Taking into account this additional detail, your initial text could have been better.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Jonathan Gibbons-2
In reply to this post by Kevin Rushforth-2
On Thu, 1 Apr 2021 12:45:52 GMT, Kevin Rushforth <[hidden email]> wrote:

>> I guess openjdk shows file history from 7u23 onwards IIRC so not sure why it is showing "Initial load" and not who/what removed it. Maybe the spec wordings actually was not there but some javadoc trickery was adding the javadoc comment in to the spec document seeing it's overidden from JComponent....
>> I am not sure what needs to be done here...
>
> @prsadhuk You could always add `@inheritDoc` like this:
>
> /**
>  * {@inheritDoc}
>  */

Starting in JDK 10, the default behavior of the standard doclet was
changed so that if a method is just being overridden for implementation
reasons, and there is no change in the public spec or signature, then
the method will not be listed in the main part of the summary table and
corresponding details section.  Instead, it will just be listed along
with other inherited methods at the end of the summary section, in a
list which is renamed from "Methods inherited from ..." to "Methods
declared in ..."

To be clear, this behavior only applies when there is nothing new to
document about the overriding method.

"No change in spec" means either no doc comment or a comment that is
just `/** ***@***.***Doc} */`.

"No change in signature" covers publicly visibly changes like covariant
return, change in modifiers, change in throws list, etc.

You can change the behavior on a per-instance behavior by providing
additional changes in the doc comment.

javadoc still supports the old style of doc generation with a
command-line option, but for JDK docs, the default is the new behavior I
described.

-- Jon

On 4/1/21 5:43 AM, Kevin Rushforth wrote:
-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Prasanta Sadhukhan-2
On Thu, 1 Apr 2021 14:10:08 GMT, Jonathan Gibbons <[hidden email]> wrote:

>> @prsadhuk You could always add `@inheritDoc` like this:
>>
>> /**
>>  * {@inheritDoc}
>>  */
>
> Starting in JDK 10, the default behavior of the standard doclet was
> changed so that if a method is just being overridden for implementation
> reasons, and there is no change in the public spec or signature, then
> the method will not be listed in the main part of the summary table and
> corresponding details section.  Instead, it will just be listed along
> with other inherited methods at the end of the summary section, in a
> list which is renamed from "Methods inherited from ..." to "Methods
> declared in ..."
>
> To be clear, this behavior only applies when there is nothing new to
> document about the overriding method.
>
> "No change in spec" means either no doc comment or a comment that is
> just `/** {@inheritDoc} */` or its whitespace equivalent.
>
> "No change in signature" covers publicly visibly changes like covariant
> return, change in modifiers, change in throws list, etc.
>
> You can change the behavior on a per-instance behavior by providing
> additional changes in the doc comment.
>
> javadoc still supports the old style of doc generation with a
> command-line option, but for JDK docs, the default is the new behavior I
> described.
>
> -- Jon
>
> On 4/1/21 5:43 AM, Kevin Rushforth wrote:
>>
>> The |javadoc| tool (or the standard doclet) used to automatically copy
>> the description from the superclass, and it seems that it no longer
>> does. Perhaps @jonathan-gibbons
>> <https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw$>
>> could comment on this change?
>>
>> —
>> You are receiving this because you were mentioned.
>> Reply to this email directly, view it on GitHub
>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtiQlz8B-g$>,
>> or unsubscribe
>> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw$>.
>>

>
> Starting in JDK 10, the default behavior of the standard doclet was changed so that if a method is just being overridden for implementation reasons, and there is no change in the public spec or signature, then the method will not be listed in the main part of the summary table and corresponding details section.  Instead, it will just be listed along with other inherited methods at the end of the summary section, in a list which is renamed from "Methods inherited from ..." to "Methods declared in ..." To be clear, this behavior only applies when there is nothing new to document about the overriding method. "No change in spec" means either no doc comment or a comment that is just `/** {@inheritdoc} */` or its whitespace equivalent. "No change in signature" covers publicly visibly changes like covariant return, change in modifiers, change in throws list, etc. You can change the behavior on a per-instance behavior by providing additional changes in the doc comment. javadoc still suppor
 ts the old style of doc generation with a command-line option, but for JDK docs, the default is the new behavior I described.
> […](#)
> -- Jon
> On 4/1/21 5:43 AM, Kevin Rushforth wrote: The |javadoc| tool (or the standard doclet) used to automatically copy the description from the superclass, and it seems that it no longer does. Perhaps @jonathan-gibbons <[https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw$](https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw%24)> could comment on this change? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <[https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtiQlz8B-g$](https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ
 -wPR9Lk254rhfVFX79WhAtiQlz8B-g%24)>, or unsubscribe <[https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw$](https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw%24)>.

So, are you saying that even if we provide @inheritDoc, it will not be listed if there is no change in spec compared to super class?

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Jonathan Gibbons-2
On Thu, 1 Apr 2021 15:25:44 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

>> Starting in JDK 10, the default behavior of the standard doclet was
>> changed so that if a method is just being overridden for implementation
>> reasons, and there is no change in the public spec or signature, then
>> the method will not be listed in the main part of the summary table and
>> corresponding details section.  Instead, it will just be listed along
>> with other inherited methods at the end of the summary section, in a
>> list which is renamed from "Methods inherited from ..." to "Methods
>> declared in ..."
>>
>> To be clear, this behavior only applies when there is nothing new to
>> document about the overriding method.
>>
>> "No change in spec" means either no doc comment or a comment that is
>> just `/** {@inheritDoc} */` or its whitespace equivalent.
>>
>> "No change in signature" covers publicly visibly changes like covariant
>> return, change in modifiers, change in throws list, etc.
>>
>> You can change the behavior on a per-instance behavior by providing
>> additional changes in the doc comment.
>>
>> javadoc still supports the old style of doc generation with a
>> command-line option, but for JDK docs, the default is the new behavior I
>> described.
>>
>> -- Jon
>>
>> On 4/1/21 5:43 AM, Kevin Rushforth wrote:
>>>
>>> The |javadoc| tool (or the standard doclet) used to automatically copy
>>> the description from the superclass, and it seems that it no longer
>>> does. Perhaps @jonathan-gibbons
>>> <https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw$>
>>> could comment on this change?
>>>
>>> —
>>> You are receiving this because you were mentioned.
>>> Reply to this email directly, view it on GitHub
>>> <https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtiQlz8B-g$>,
>>> or unsubscribe
>>> <https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw$>.
>>>
>
>>
>> Starting in JDK 10, the default behavior of the standard doclet was changed so that if a method is just being overridden for implementation reasons, and there is no change in the public spec or signature, then the method will not be listed in the main part of the summary table and corresponding details section.  Instead, it will just be listed along with other inherited methods at the end of the summary section, in a list which is renamed from "Methods inherited from ..." to "Methods declared in ..." To be clear, this behavior only applies when there is nothing new to document about the overriding method. "No change in spec" means either no doc comment or a comment that is just `/** {@inheritdoc} */` or its whitespace equivalent. "No change in signature" covers publicly visibly changes like covariant return, change in modifiers, change in throws list, etc. You can change the behavior on a per-instance behavior by providing additional changes in the doc comment. javadoc still suppo
 rts the old style of doc generation with a command-line option, but for JDK docs, the default is the new behavior I described.
>> […](#)
>> -- Jon
>> On 4/1/21 5:43 AM, Kevin Rushforth wrote: The |javadoc| tool (or the standard doclet) used to automatically copy the description from the superclass, and it seems that it no longer does. Perhaps @jonathan-gibbons <[https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw$](https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw%24)> could comment on this change? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <[https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtiQlz8B-g$](https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgA
 J-wPR9Lk254rhfVFX79WhAtiQlz8B-g%24)>, or unsubscribe <[https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw$](https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw%24)>.
>
> So, are you saying that even if we provide @inheritDoc, it will not be listed if there is no change in spec compared to super class?

On 4/1/21 8:26 AM, Prasanta Sadhukhan wrote:
>
> So, are you saying that even if we provide @inheritdoc
> <https://urldefense.com/v3/__https://github.com/inheritdoc__;!!GqivPVa7Brio!OR4b9howuG4BpVugrQEdNUuVqpxPta_Ff7BnXWbd-LDSRQ9jjAQ4mdGVtd097q0D29aUBA$>,
> it will not be listed if there is no change in spec compared to super
> class?
>

Yes.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec [v3]

Prasanta Sadhukhan-2
In reply to this post by Prasanta Sadhukhan-2
> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
> has no spec.
> Added spec for the method.

Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:

  javadoc change

-------------

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3213/files
  - new: https://git.openjdk.java.net/jdk/pull/3213/files/e2f1d259..f8d2da21

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=3213&range=02
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=3213&range=01-02

  Stats: 5 lines in 1 file changed: 4 ins; 0 del; 1 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3213.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3213/head:pull/3213

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Sergey Bylokhov-2
In reply to this post by Jonathan Gibbons-2
On Thu, 1 Apr 2021 15:29:34 GMT, Jonathan Gibbons <[hidden email]> wrote:

>>>
>>> Starting in JDK 10, the default behavior of the standard doclet was changed so that if a method is just being overridden for implementation reasons, and there is no change in the public spec or signature, then the method will not be listed in the main part of the summary table and corresponding details section.  Instead, it will just be listed along with other inherited methods at the end of the summary section, in a list which is renamed from "Methods inherited from ..." to "Methods declared in ..." To be clear, this behavior only applies when there is nothing new to document about the overriding method. "No change in spec" means either no doc comment or a comment that is just `/** {@inheritdoc} */` or its whitespace equivalent. "No change in signature" covers publicly visibly changes like covariant return, change in modifiers, change in throws list, etc. You can change the behavior on a per-instance behavior by providing additional changes in the doc comment. javadoc still supp
 orts the old style of doc generation with a command-line option, but for JDK docs, the default is the new behavior I described.
>>> […](#)
>>> -- Jon
>>> On 4/1/21 5:43 AM, Kevin Rushforth wrote: The |javadoc| tool (or the standard doclet) used to automatically copy the description from the superclass, and it seems that it no longer does. Perhaps @jonathan-gibbons <[https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw$](https://urldefense.com/v3/__https://github.com/jonathan-gibbons__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtjxN8g4zw%24)> could comment on this change? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <[https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtiQlz8B-g$](https://urldefense.com/v3/__https://github.com/openjdk/jdk/pull/3213*issuecomment-811880830__;Iw!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmg
 AJ-wPR9Lk254rhfVFX79WhAtiQlz8B-g%24)>, or unsubscribe <[https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw$](https://urldefense.com/v3/__https://github.com/notifications/unsubscribe-auth/AOUXBRUGHOZZ4X3NOBWRX63TGRS55ANCNFSM4Z3HDOJA__;!!GqivPVa7Brio!Nt46yROIsMrLvPBMvzgGTeSnhOvHtuHlNczVmgAJ-wPR9Lk254rhfVFX79WhAtg5YRT3Kw%24)>.

>>
>> So, are you saying that even if we provide @inheritDoc, it will not be listed if there is no change in spec compared to super class?
>
> On 4/1/21 8:26 AM, Prasanta Sadhukhan wrote:
>>
>> So, are you saying that even if we provide @inheritdoc
>> <https://urldefense.com/v3/__https://github.com/inheritdoc__;!!GqivPVa7Brio!OR4b9howuG4BpVugrQEdNUuVqpxPta_Ff7BnXWbd-LDSRQ9jjAQ4mdGVtd097q0D29aUBA$>,
>> it will not be listed if there is no change in spec compared to super
>> class?
>>
>
> Yes.

The method was overridden to change the implementation without changing of specification. This is exactly the case that was changed in the JavaDoc tool in jdk10. For this case, the JavaDoc tool decided to skip spec generation, it is a feature.
So this is not a bug in the Swing, probably it is a bug in the JavaDoc tool, maybe not a bug at all.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec [v3]

Alexey Ivanov-2
In reply to this post by Prasanta Sadhukhan-2
On Thu, 1 Apr 2021 15:48:53 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

>> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
>> has no spec.
>> Added spec for the method.
>
> Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:
>
>   javadoc change

src/java.desktop/share/classes/javax/swing/JMenu.java line 1259:

> 1257:
> 1258:     /**
> 1259:      * Sets the orientation for this menu and the associated popup component

Suggestion:

     * Sets the orientation for this menu and the associated popup menu
I think *popup component* isn't specific enough.

Maybe “and *its* associated…” is even better?

src/java.desktop/share/classes/javax/swing/JMenu.java line 1260:

> 1258:     /**
> 1259:      * Sets the orientation for this menu and the associated popup component
> 1260:      * determined by the <code>ComponentOrientation</code> argument.

Suggestion:

     * determined by the {@code ComponentOrientation} argument.
The new code should use javadoc syntax.

src/java.desktop/share/classes/javax/swing/JMenu.java line 1265:

> 1263:      *        the popup menu component contained within it.
> 1264:      */
> 1265:     public void setComponentOrientation(ComponentOrientation o) {

For consistency, I suggest using the same wording here as in the introduction sentence.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec [v4]

Prasanta Sadhukhan-2
In reply to this post by Prasanta Sadhukhan-2
> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
> has no spec.
> Added spec for the method.

Prasanta Sadhukhan has updated the pull request incrementally with two additional commits since the last revision:

 - javadoc change
 - javadoc change

-------------

Changes:
  - all: https://git.openjdk.java.net/jdk/pull/3213/files
  - new: https://git.openjdk.java.net/jdk/pull/3213/files/f8d2da21..8a4645b2

Webrevs:
 - full: https://webrevs.openjdk.java.net/?repo=jdk&pr=3213&range=03
 - incr: https://webrevs.openjdk.java.net/?repo=jdk&pr=3213&range=02-03

  Stats: 4 lines in 1 file changed: 0 ins; 0 del; 4 mod
  Patch: https://git.openjdk.java.net/jdk/pull/3213.diff
  Fetch: git fetch https://git.openjdk.java.net/jdk pull/3213/head:pull/3213

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec

Alexey Ivanov-2
In reply to this post by Sergey Bylokhov-2
On Thu, 1 Apr 2021 15:52:49 GMT, Sergey Bylokhov <[hidden email]> wrote:

> The method was overridden to change the implementation without changing of specification.

This might have been overlooked. The overridden method changes the behaviour. I'm for documenting the updated behaviour.

> This is exactly the case that was changed in the JavaDoc tool in jdk10. For this case, the JavaDoc tool decided to skip spec generation, it is a feature. So this is not a bug in the Swing, probably it is a bug in the JavaDoc tool, maybe not a bug at all.

It looks as the intentional change in the javadoc tool.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec [v3]

Prasanta Sadhukhan-2
In reply to this post by Alexey Ivanov-2
On Thu, 1 Apr 2021 15:50:28 GMT, Alexey Ivanov <[hidden email]> wrote:

>> Prasanta Sadhukhan has updated the pull request incrementally with one additional commit since the last revision:
>>
>>   javadoc change
>
> src/java.desktop/share/classes/javax/swing/JMenu.java line 1260:
>
>> 1258:     /**
>> 1259:      * Sets the orientation for this menu and the associated popup component
>> 1260:      * determined by the <code>ComponentOrientation</code> argument.
>
> Suggestion:
>
>      * determined by the {@code ComponentOrientation} argument.
> The new code should use javadoc syntax.

I did not change it as then we may need to change `applyComponentOrientation` which uses the same syntax. It will look odd having different syntax in same file.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
Reply | Threaded
Open this post in threaded view
|

Re: <Swing Dev> RFR: 8264218: Public method javax.swing.JMenu.setComponentOrientation() has no spec [v4]

Alexey Ivanov-2
In reply to this post by Prasanta Sadhukhan-2
On Thu, 1 Apr 2021 16:08:48 GMT, Prasanta Sadhukhan <[hidden email]> wrote:

>> A public overriding method JMenu.setComponentOrientation(java.awt.ComponentOrientation)
>> has no spec.
>> Added spec for the method.
>
> Prasanta Sadhukhan has updated the pull request incrementally with two additional commits since the last revision:
>
>  - javadoc change
>  - javadoc change

src/java.desktop/share/classes/javax/swing/JMenu.java line 1263:

> 1261:      *
> 1262:      * @param o the new orientation for this menu and
> 1263:      *        its associated popup menu contained within it.

I'd rather remove “contained within it”.

-------------

PR: https://git.openjdk.java.net/jdk/pull/3213
12