<AWT Dev> <Swing Dev> 8138771: java.awt.image.AbstractMultiResolutionImage needs customized spec for methods of Image which it implements

[Jim Graham]

I agree that the @return tags need to be filled in.

In the first descriptive sentence of the delegation methods, note that "{@code getBaseImage()}" is a reference to a 
function and not an object, so it sounds like the methods are implemented as "return getBaseImage()" which is not valid 
because the image is not the return value.  If you want to provide a code reference there, then it would be better to 
say that:

* This method simply delegates to the image returned from the
* {@code #getBaseImage()} method.

Also, since you provide pseudo-code equivalent for all of the methods, which suffices to demonstrate the relationship 
with the getBaseImage() method, I think the first reference could simply be the words "base image", especially since you 
are referring to the concept of a base image rather than the actual method that returns it, as in:

* This method simply delegates to the base image.
* It is equivalent to: ...

(Or)

* This method simply delegates to the same method on the base image.
* It is equivalent to: ...

Also, I'd change the getGraphics description to the following, detailing why we throw the exception:

* As per the contract of the base {@code Image#getGraphics()} method,
* this implementation will always throw {@code UnsupportedOperationException}
* since only off-screen images can return a {@code Graphics} object.

			...jim

On 8/30/16 3:47 AM, Alexandr Scherbatiy wrote:
> On 8/30/2016 12:17 PM, Avik Niyogi wrote:
>> Hi All,
>> Please review the proposed specification for JDK9 including inputs from reviewer reviews.
>>
>> *http://cr.openjdk.java.net/~aniyogi/8138771/webrev.02/* <http://cr.openjdk.java.net/%7Eaniyogi/8138771/webrev.02/>
>>
>   I believe the @return tag should have a simple description in other case the compilation fails because of enabled
> javadoc warning errors.
>
>   Thanks,
>   Alexandr.
>
>> Thank you in advance.
>>
>> With Regards,
>> Avik Niyogi
>>
>>> On 29-Aug-2016, at 5:55 pm, Alexandr Scherbatiy <alexandr.scherbatiy at oracle.com
>>> <mailto:alexandr.scherbatiy at oracle.com>> wrote:
>>>
>>> On 8/29/2016 9:52 AM, Avik Niyogi wrote:
>>>> Hi All,
>>>>
>>>> Please review the proposed specification for JDK9 including inputs from reviver reviews.
>>>>
>>>> *http://cr.openjdk.java.net/~aniyogi/8138771/webrev.01/ <http://cr.openjdk.java.net/%7Eaniyogi/8138771/webrev.01/>*
>>>>
>>>   There is the {@inheritDoc} which allows to use a javadoc from the parent method.
>>>   Javadoc for AbstractMultiResolutionImage.getWidth()/getHeight()/getSource()/getProperty() could be like:
>>>
>>>     /**
>>>      * This method simply delegates to the {@code getBaseImage()}.
>>>      * It is equivalent to: {@code getBaseImage().getWidth(observer)).
>>>      *
>>>      * @see #getBaseImage
>>>      *
>>>      * @since 9
>>>      */
>>>
>>>   Thanks,
>>>   Alexandr.
>>>
>>>> Thank you in advance.
>>>>
>>>> With Regards,
>>>> Avik Niyogi
>>>>
>>>>> On 23-Aug-2016, at 2:58 pm, Alexander Scherbatiy <alexandr.scherbatiy at oracle.com
>>>>> <mailto:alexandr.scherbatiy at oracle.com>> wrote:
>>>>>
>>>>> On 22/08/16 11:06, Avik Niyogi wrote:
>>>>>> + awt-dev
>>>>>>
>>>>>>
>>>>>>> On 22-Aug-2016, at 12:28 pm, Avik Niyogi <avik.niyogi at oracle.com <mailto:avik.niyogi at oracle.com>> wrote:
>>>>>>>
>>>>>>> Hi All,
>>>>>>>
>>>>>>> Kindly review the proposed specifications for JDK9.
>>>>>>>
>>>>>>> *Bug: https://bugs.openjdk.java.net/browse/JDK-8138771*
>>>>>>>
>>>>>>> *Webrev: http://cr.openjdk.java.net/~aniyogi/8138771/webrev.00/
>>>>>>> <http://cr.openjdk.java.net/%7Eaniyogi/8138771/webrev.00/>*
>>>>>>>
>>>>>>> *Issue: *The customised specifications necessitated for getGraphics method did not exist.
>>>>>>>  So test cases created according to derived specifications would lead to test cases failures.
>>>>>>>
>>>>>>> *Cause: * No congruous specifications could elicit failure in circumstances not encompassed
>>>>>>> in test cases generated without the knowledge of the same.
>>>>>>>
>>>>>>> *Fix:* Appropriate comprehensive specifications required were added.
>>>>> -  I am not a native speaker. May be something like this would be better:
>>>>> ------
>>>>>     /**
>>>>>      * This method is not supported by {@code AbstractMultiResolutionImage}
>>>>>      * and always throws {@code UnsupportedOperationException}
>>>>>      *
>>>>>      * @return {@code UnsupportedOperationException} is thrown
>>>>>      * @throws UnsupportedOperationException this method is not supported
>>>>> ------
>>>>>
>>>>> - others overridden method should have a documentation that they delegate call to the base image (see #getBaseImage)
>>>>>
>>>>> Thanks,
>>>>> Alexandr.
>>>>>
>>>>>>>
>>>>>>> With Regards,
>>>>>>> Avik Niyogi
>>>>>>
>>>>>
>>>>
>>>
>>
>