RFR: JDK-8217393 Re: Clarification in Attributes equal

[Lance Andersen]

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> wrote:
> 
>> 
>> On Jan 22, 2019, at 12:02 PM, Alan Bateman <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>>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>>

 <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>