RFR: JDK-8217393 Re: Clarification in Attributes equal
Lance Andersen
lance.andersen at oracle.com
Fri Jan 25 20:05:49 UTC 2019
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.java Thu Jan 24 10:57:31 2019 -0800
+++ b/src/java.base/share/classes/java/util/jar/Attributes.java Fri 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> 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.java Thu Jan 24 10:57:31 2019 -0800
>>> +++ b/src/java.base/share/classes/java/util/jar/Attributes.java Fri 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 <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 <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 <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>>>> <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 <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>>> <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>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>
>>>
>>> <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>> <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>> <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>
More information about the core-libs-dev
mailing list