RFR: JDK-8217393 Re: Clarification in Attributes equal

Joe Darcy joe.darcy at oracle.com
Fri Jan 25 20:42:49 UTC 2019 

I don't mind if Intellij is happier :-)

-Joe

On 1/25/2019 12:05 PM, Lance Andersen wrote:
>
>
> While this works fine in the generated javadoc {@linkplain map map}
>
> This makes intellij a bit happier : {@linkplain Attributes#map map}
>
>
> ---------------------
> $ hg diff
> diff -r 6130409b923e 
> src/java.base/share/classes/java/util/jar/Attributes.java
> --- a/src/java.base/share/classes/java/util/jar/Attributes.javaThu Jan 
> 24 10:57:31 2019 -0800
> +++ b/src/java.base/share/classes/java/util/jar/Attributes.javaFri Jan 
> 25 15:04:03 2019 -0500
> @@ -265,9 +265,10 @@
>      }
>
>
>      /**
> -     * Compares the specified Attributes object with this Map for 
> equality.
> -     * Returns true if the given object is also an instance of Attributes
> -     * and the two Attributes objects represent the same mappings.
> +     * Compares the specified object to the underlying
> +     * {@linkplain Attributes#map map} for equality.
> +     * Returns true if the given object is also a Map
> +     * and the two maps represent the same mappings.
>       *
>       * @param o the Object to be compared
>       * @return true if the specified Object is equal to this Map
> ---------------------
>> On Jan 25, 2019, at 2:53 PM, Lance Andersen 
>> <lance.andersen at oracle.com <mailto:lance.andersen at oracle.com>> wrote:
>>
>> Hi Joe
>>
>> yes I checked it in my local build and it does take me to map field 
>> via the link
>>
>> Best
>> Lance
>>> On Jan 25, 2019, at 2:49 PM, Joe Darcy <joe.darcy at oracle.com 
>>> <mailto:joe.darcy at oracle.com>> wrote:
>>>
>>> Hi Lance,
>>>
>>> Assuming the javadoc renders as expected, the new version looks good 
>>> to me :-)
>>>
>>> Thanks,
>>> -Joe
>>> On 1/25/2019 11:44 AM, Lance Andersen wrote:
>>>> Thank you Joe.
>>>>
>>>> So the change is (see bolded change):
>>>>
>>>> $ hg diff
>>>> diff -r 6130409b923e 
>>>> src/java.base/share/classes/java/util/jar/Attributes.java
>>>> --- a/src/java.base/share/classes/java/util/jar/Attributes.javaThu 
>>>> Jan 24 10:57:31 2019 -0800
>>>> +++ b/src/java.base/share/classes/java/util/jar/Attributes.javaFri 
>>>> Jan 25 14:44:12 2019 -0500
>>>> @@ -265,9 +265,10 @@
>>>>     }
>>>>
>>>>
>>>>     /**
>>>> -     * Compares the specified Attributes object with this Map for 
>>>> equality.
>>>> -     * Returns true if the given object is also an instance of 
>>>> Attributes
>>>> -     * and the two Attributes objects represent the same mappings.
>>>> +     * Compares the specified object to the underlying
>>>> +     * {@linkplain map map} for equality.
>>>> +     * Returns true if the given object is also a Map
>>>> +     * and the two maps represent the same mappings.
>>>>      *
>>>>      * @param o the Object to be compared
>>>>      * @return true if the specified Object is equal to this Map
>>>>
>>>>> On Jan 25, 2019, at 2:28 PM, Joe Darcy <joe.darcy at oracle.com 
>>>>> <mailto:joe.darcy at oracle.com><mailto:joe.darcy at oracle.com>> wrote:
>>>>>
>>>>> To clarify the CSR comments, for "underlying map" I meant for 
>>>>> "map" to be a link to the protected field named "map".
>>>>>
>>>>> Thanks,
>>>>>
>>>>> -Joe
>>>>>
>>>>> On 1/25/2019 11:24 AM, Roger Riggs wrote:
>>>>>> Looks fine, Lance
>>>>>>
>>>>>> Roger
>>>>>>
>>>>>> On 01/25/2019 02:22 PM, Lance Andersen wrote:
>>>>>>> The CSR review suggested a slight update to the proposed wording:
>>>>>>>
>>>>>>> ———————
>>>>>>> $ hg diff
>>>>>>> diff -r 6130409b923e 
>>>>>>> src/java.base/share/classes/java/util/jar/Attributes.java
>>>>>>> --- a/src/java.base/share/classes/java/util/jar/Attributes.java 
>>>>>>> Thu Jan 24 10:57:31 2019 -0800
>>>>>>> +++ b/src/java.base/share/classes/java/util/jar/Attributes.java 
>>>>>>> Fri Jan 25 14:20:51 2019 -0500
>>>>>>> @@ -265,10 +265,11 @@
>>>>>>>      }
>>>>>>>        /**
>>>>>>> -     * Compares the specified Attributes object with this Map 
>>>>>>> for equality.
>>>>>>> -     * Returns true if the given object is also an instance of 
>>>>>>> Attributes
>>>>>>> -     * and the two Attributes objects represent the same mappings.
>>>>>>> -     *
>>>>>>> +     * Compares the specified object to the underlying
>>>>>>> +     * {@linkplain java.util.Map Map} for equality.
>>>>>>> +     * Returns true if the given object is also a Map
>>>>>>> +     * and the two maps represent the same mappings.
>>>>>>> +     *
>>>>>>>       * @param o the Object to be compared
>>>>>>>       * @return true if the specified Object is equal to this Map
>>>>>>>       */
>>>>>>>
>>>>>>> —————————
>>>>>>>
>>>>>>> Best
>>>>>>> Lance
>>>>>>>> On Jan 22, 2019, at 7:47 PM, Lance Andersen 
>>>>>>>> <lance.andersen at oracle.com 
>>>>>>>> <mailto:lance.andersen at oracle.com><mailto:lance.andersen at oracle.com>> 
>>>>>>>> wrote:
>>>>>>>>
>>>>>>>>> On Jan 22, 2019, at 12:02 PM, Alan Bateman 
>>>>>>>>> <Alan.Bateman at oracle.com 
>>>>>>>>> <mailto:Alan.Bateman at oracle.com><mailto:Alan.Bateman at oracle.com>> 
>>>>>>>>> wrote:
>>>>>>>>>
>>>>>>>>> On 19/01/2019 12:46, Lance Andersen wrote:
>>>>>>>>>> Hi all,
>>>>>>>>>>
>>>>>>>>>> Please review the  fix for JDK-8217393 which updates the 
>>>>>>>>>> javadocs for Attriibutes::equals to clarify its behavior to 
>>>>>>>>>> match its implementation
>>>>>>>>>>
>>>>>>>>>> —————
>>>>>>>>>> hg diff
>>>>>>>>>> diff -r c5d6b4480c6c 
>>>>>>>>>> src/java.base/share/classes/java/util/jar/Attributes.java
>>>>>>>>>> --- 
>>>>>>>>>> a/src/java.base/share/classes/java/util/jar/Attributes.java 
>>>>>>>>>> Thu Jan 17 13:46:12 2019 -0800
>>>>>>>>>> +++ 
>>>>>>>>>> b/src/java.base/share/classes/java/util/jar/Attributes.java 
>>>>>>>>>> Sat Jan 19 07:35:55 2019 -0500
>>>>>>>>>> @@ -265,9 +265,10 @@
>>>>>>>>>>     }
>>>>>>>>>>       /**
>>>>>>>>>> -     * Compares the specified Attributes object with this 
>>>>>>>>>> Map for equality.
>>>>>>>>>> -     * Returns true if the given object is also an instance 
>>>>>>>>>> of Attributes
>>>>>>>>>> -     * and the two Attributes objects represent the same 
>>>>>>>>>> mappings.
>>>>>>>>>> +     * Compares the specified object with this Map for equality.
>>>>>>>>>> +     * Returns true if the given object is also a Map
>>>>>>>>>> +     * and the two objects represent the same Manifest
>>>>>>>>>> +     * attribute name-value mappings.
>>>>>>>>>>
>>>>>>>>> I think this looks okay although I like Martin's suggestion to 
>>>>>>>>> just inherit the javadoc as Attributes is a Map.
>>>>>>>> I had thought about that but felt that keeping the javadoc 
>>>>>>>> similar to what it has been might be the better approach given 
>>>>>>>> it has been around since JDK 1.2
>>>>>>>>
>>>>>>>> If we were to inherit the javadoc, we should probably look at 
>>>>>>>> the rest of the methods to see where else it would  make sense 
>>>>>>>> to inherit the javadoc
>>>>>>>>
>>>>>>>> Best
>>>>>>>> Lance
>>>>>>>>> -Alan
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>>>
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>>> 
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>>>
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>>>Lance 
>>>>>>>> Andersen| Principal Member of Technical Staff | +1.781.442.2037
>>>>>>>> Oracle Java Engineering
>>>>>>>> 1 Network Drive
>>>>>>>> Burlington, MA 01803
>>>>>>>> Lance.Andersen at oracle.com 
>>>>>>>> <mailto:Lance.Andersen at oracle.com><mailto:Lance.Andersen at oracle.com> 
>>>>>>>> <mailto:Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>> 
>>>>>>>> <mailto:Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com> 
>>>>>>>> <mailto:Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>>>
>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>>
>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>> 
>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>>
>>>>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif<http://oracle.com/us/design/oracle-email-sig-198324.gif>>Lance 
>>>>>>> Andersen| Principal Member of Technical Staff | +1.781.442.2037
>>>>>>> Oracle Java Engineering
>>>>>>> 1 Network Drive
>>>>>>> Burlington, MA 01803
>>>>>>> Lance.Andersen at oracle.com 
>>>>>>> <mailto:Lance.Andersen at oracle.com><mailto:Lance.Andersen at oracle.com> 
>>>>>>> <mailto:Lance.Andersen at oracle.com<mailto:Lance.Andersen at oracle.com>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>
>>>>
>>>> <oracle_sig_logo.gif> 
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>>>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance 
>>>> Andersen| Principal Member of Technical Staff | +1.781.442.2037
>>>> Oracle Java Engineering
>>>> 1 Network Drive
>>>> Burlington, MA 01803
>>>> Lance.Andersen at oracle.com 
>>>> <mailto:Lance.Andersen at oracle.com><mailto:Lance.Andersen at oracle.com>
>>>>
>>>>
>>>>
>>
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif> 
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
>> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance 
>> Andersen| Principal Member of Technical Staff | +1.781.442.2037
>> Oracle Java Engineering
>> 1 Network Drive
>> Burlington, MA 01803
>> Lance.Andersen at oracle.com 
>> <mailto:Lance.Andersen at oracle.com><mailto:Lance.Andersen at oracle.com>
>
> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
> <http://oracle.com/us/design/oracle-email-sig-198324.gif><http://oracle.com/us/design/oracle-email-sig-198324.gif>
> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance 
> Andersen| Principal Member of Technical Staff | +1.781.442.2037
> Oracle Java Engineering
> 1 Network Drive
> Burlington, MA 01803
> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>
>
>
>

More information about the core-libs-dev mailing list