<AWT Dev> [9] Review request for 7081580: Specification for MouseInfo.getNumberOfButtons() doesn't contain info about "awt.mouse.numButtons"

[Phil Race]

Unless you intend to document that property here :-
http://docs.oracle.com/javase/8/docs/api/java/awt/doc-files/DesktopProperties.html

maybe it should not be mentioned ..

-phil.

On 3/17/2015 4:16 PM, Sergey Bylokhov wrote:
> +1
>
> 16.03.15 7:32, Anton V. Tarasov wrote:
>> Hi Semyon,
>>
>> As a minimalistic description of the property, this looks ok to me. 
>> So, if there's nothing else to say about it, I'm fine with the fix.
>>
>> Regards,
>> Anton.
>>
>> On 16.03.2015 16:22, Semyon Sadetsky wrote:
>>> Hi!
>>>
>>> Thank you Anton!
>>> The updated webrev is: 
>>> http://cr.openjdk.java.net/~alexsch/semyon-sadetsky/7081580/webrev.01/
>>>
>>> --Semyon
>>>
>>>
>>> On 3/12/2015 1:42 PM, Anton V. Tarasov wrote:
>>>> Hi Semyon, Sergey,
>>>>
>>>> I agree with that the modified javadoc is not good.
>>>>
>>>> 1. When you say something is done "by calling A.b()", it means I 
>>>> can write exactly "A.b()" in my code and this will do the job. 
>>>> However, that's not the case with Toolkit.getDesktopProperty() (it 
>>>> won't be compiled).
>>>>
>>>> In order to refer to a method, you can use either of the following 
>>>> constructions:
>>>>
>>>> a) the A.b() method
>>>> b) {@link A#b}
>>>> c) the {@link A#b} method
>>>>
>>>> b/c is preferrable.
>>>>
>>>> 2. When you say "The value is obtained by calling something", it's 
>>>> not quite clear what or who obtains the value. The method itself? 
>>>> Or this is an alternative way to get it for a user?
>>>>
>>>> 3. If this is the only place in the spec where the property is 
>>>> introduced, then you should somehow reflect this fact. For 
>>>> instance, like this:
>>>>
>>>> The value is set by the "awt.mouse.numButtons" property, which can 
>>>> be obtained directly with the {@link Toolkit#getDesktopProperty} 
>>>> method.
>>>>
>>>> You don't have to _specify_ the way getNumberOfButtons() obtains 
>>>> the property, unless this implementation detail should really be 
>>>> specified. (For instance, if it was obtained by a method which 
>>>> could be overriden in an application.)
>>>>
>>>> Thanks,
>>>> Anton.
>>>>
>>>>
>>>> On 12.03.2015 11:42, Semyon Sadetsky wrote:
>>>>> Sorry, Sergey. Still don't understand what you mean.
>>>>> The issue is about*to do**mention* "awt.mouse.numButtons".
>>>>> Now you are saying that there is no value to mention it for the 
>>>>> first time in this spec. Doesn't it contradict to the request itself?
>>>>> You couldn't be more specific on what do you want, could you?
>>>>> The fix just adds one short statement to the spec.  Maybe you'll 
>>>>> find it to be more productive to just rephrase as you want and 
>>>>> write here.
>>>>>
>>>>> Thank you!
>>>>> --Semyon
>>>>>
>>>>> On 3/12/2015 11:11 AM, Sergey Bylokhov wrote:
>>>>>> Hi, Semyon.
>>>>>> That's a specification which should be read as written. But if 
>>>>>> you mean this is not the same things, then it is unclear what 
>>>>>> value will be added to the description of "awt.mouse.numButtons" 
>>>>>> property, which mentions in the specification for the first time. 
>>>>>> Since getNumberOfButtons obtain something not specified from the 
>>>>>> getToolkit, modify it somehow(w/o specification) and returns. See 
>>>>>> for example Toolkit.getToolkit and Toolkit. 
>>>>>> areExtraMouseButtonsEnabled(). It is not necessary write so 
>>>>>> specific specification but at least it should be clear.
>>>>>>
>>>>>> It would be good to rephrase it somehow.
>>>>>>
>>>>>> 12.03.15 0:09, Semyon Sadetsky wrote:
>>>>>>> Hi Sergey,
>>>>>>>
>>>>>>> I didn't find any mention in the new text that the method 
>>>>>>> returns the same value as Tolkit.get... returns.
>>>>>>> I'm not an expert in English but in my opinion "obtained by" 
>>>>>>> verb doesn't state that the same value is returned without any 
>>>>>>> handling.
>>>>>>> Maybe you've mixed it up with "proxy"?
>>>>>>>
>>>>>>> Thanks,
>>>>>>> --Semyon
>>>>>>>
>>>>>>>
>>>>>>> On 3/12/2015 9:47 AM, Sergey Bylokhov wrote:
>>>>>>>> Hi, Semyon.
>>>>>>>> The fix in general is correct, but it adds an assertion that 
>>>>>>>> this method should return the same values as Toolkit.get...
>>>>>>>> And this is incorrect, and we can get a new CR that 
>>>>>>>> implementation don't follow the specification. Probably we can 
>>>>>>>> simplify it and state that we use numeric value from desktop 
>>>>>>>> property or something like that?
>>>>>>>>
>>>>>>>> 11.03.15 22:52, Semyon Sadetsky wrote:
>>>>>>>>> Hello,
>>>>>>>>>
>>>>>>>>> please review fix for jdk9.
>>>>>>>>>
>>>>>>>>> Webrev: 
>>>>>>>>> http://cr.openjdk.java.net/~alexsch/semyon-sadetsky/7081580/webrev.00/ 
>>>>>>>>>
>>>>>>>>> Bug: https://bugs.openjdk.java.net/browse/JDK-7081580
>>>>>>>>>
>>>>>>>>> Thanks,
>>>>>>>>> --Semyon
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>
>>>>>>
>>>>>> -- 
>>>>>> Best regards, Sergey.
>>>>>
>>>>
>>>
>>
>
>
> -- 
> Best regards, Sergey.