Uploaded image for project: 'JDK'
  1. JDK
  2. JDK-5109619

(spec) Misleading documentation in java.lang.Object.equals()

    Details

    • Subcomponent:
    • CPU:
      x86
    • OS:
      windows_xp

      Description

      Name: gm110360 Date: 09/30/2004


      A DESCRIPTION OF THE PROBLEM :
      The javadoc for the equals() method says:

      "The equals method implements an equivalence relation on non-null object references: "

      This sentence is followed by a list of 5 properties. However, this is somewhat misleading because the final two properties are not properties of an equivalence relation. This could confuse someone into thinking that those two properties *are* in fact part of the definition of an equivalence relation.


      EXPECTED VERSUS ACTUAL BEHAVIOR :
      EXPECTED -
      I would rewrite the relevant portion of the javadoc as follows:

      ...
      <p>
      The <code>equals</code> method implements an equivalence relation on non-null object references:
      <ul>
      <li>It is <i>reflexive</i>...
      <li>It is <i>symmetric</i>...
      <li>It is <i>transitive</i>...
      </ul>
      <p>
      In addition, this method satisfies the following properties:
      <ul>
      <li>It is <i>consistent</i>...
      <li>For any non-null reference value...
      </ul>
      ...
      ACTUAL -
      The doc currently says

      ...
      <p>
      The <code>equals</code> method implements an equivalence relation on non-null object references:
      <ul>
      <li>It is <i>reflexive</i>...
      <li>It is <i>symmetric</i>...
      <li>It is <i>transitive</i>...
      <li>It is <i>consistent</i>...
      <li>For any non-null reference value...
      </ul>
      ...

      URL OF FAULTY DOCUMENTATION :
      http://java.sun.com/j2se/1.5.0/docs/api/java/lang/Object.html#equals(java.lang.Object)
      (Incident Review ID: 315906)
      ======================================================================
      ###@###.### 10/4/04 18:11 GMT

        Attachments

          Activity

            People

            • Assignee:
              darcy Joe Darcy
              Reporter:
              gmanwanisunw Girish Manwani (Inactive)
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:
                Imported:
                Indexed: