JDK 8 code review request for 7112008 Javadoc for j.l.Object.finalize() vs JLS 12.6 Finalization of Class Instances

[Joe Darcy]

Hello,

Please review this small doc cleanup of java.lang.Object:

     7112008 Javadoc for j.l.Object.finalize() vs JLS 12.6 Finalization 
of Class Instances
     http://cr.openjdk.java.net/~darcy/7112008.0/

Full patch below inline.

Thanks,

-Joe

--- old/src/share/classes/java/lang/Object.java    2012-01-10 
13:04:42.000000000 -0800
+++ new/src/share/classes/java/lang/Object.java    2012-01-10 
13:04:42.000000000 -0800
@@ -58,8 +58,7 @@
       *
       * @return The {@code Class} object that represents the runtime
       *         class of this object.
-     * @see    Class Literals, section 15.8.2 of
-     * <cite>The Java™ Language Specification</cite>.
+     * @jls 15.8.2 Class Literals
       */
      public final native Class<?> getClass();

@@ -92,7 +91,7 @@
       * objects. (This is typically implemented by converting the internal
       * address of the object into an integer, but this implementation
       * technique is not required by the
-     * Java<font size="-2"><sup>TM</sup></font> programming language.)
+     * Java™ programming language.)
       *
       * @return  a hash code value for this object.
       * @see     java.lang.Object#equals(java.lang.Object)
@@ -203,7 +202,7 @@
       * exception at run time.
       *
       * @return     a clone of this instance.
-     * @exception  CloneNotSupportedException  if the object's class 
does not
+     * @throws  CloneNotSupportedException  if the object's class does not
       *               support the {@code Cloneable} interface. Subclasses
       *               that override the {@code clone} method can also
       *               throw this exception to indicate that an instance 
cannot
@@ -264,7 +263,7 @@
       * <p>
       * Only one thread at a time can own an object's monitor.
       *
-     * @exception  IllegalMonitorStateException  if the current thread 
is not
+     * @throws  IllegalMonitorStateException  if the current thread is not
       *               the owner of this object's monitor.
       * @see        java.lang.Object#notifyAll()
       * @see        java.lang.Object#wait()
@@ -288,7 +287,7 @@
       * description of the ways in which a thread can become the owner of
       * a monitor.
       *
-     * @exception  IllegalMonitorStateException  if the current thread 
is not
+     * @throws  IllegalMonitorStateException  if the current thread is not
       *               the owner of this object's monitor.
       * @see        java.lang.Object#notify()
       * @see        java.lang.Object#wait()
@@ -368,11 +367,11 @@
       * a monitor.
       *
       * @param      timeout   the maximum time to wait in milliseconds.
-     * @exception  IllegalArgumentException      if the value of timeout is
+     * @throws  IllegalArgumentException      if the value of timeout is
       *               negative.
-     * @exception  IllegalMonitorStateException  if the current thread 
is not
+     * @throws  IllegalMonitorStateException  if the current thread is not
       *               the owner of the object's monitor.
-     * @exception  InterruptedException if any thread interrupted the
+     * @throws  InterruptedException if any thread interrupted the
       *             current thread before or while the current thread
       *             was waiting for a notification.  The <i>interrupted
       *             status</i> of the current thread is cleared when
@@ -433,12 +432,12 @@
       * @param      timeout   the maximum time to wait in milliseconds.
       * @param      nanos      additional time, in nanoseconds range
       *                       0-999999.
-     * @exception  IllegalArgumentException      if the value of timeout is
+     * @throws  IllegalArgumentException      if the value of timeout is
       *                      negative or the value of nanos is
       *                      not in the range 0-999999.
-     * @exception  IllegalMonitorStateException  if the current thread 
is not
+     * @throws  IllegalMonitorStateException  if the current thread is not
       *               the owner of this object's monitor.
-     * @exception  InterruptedException if any thread interrupted the
+     * @throws  InterruptedException if any thread interrupted the
       *             current thread before or while the current thread
       *             was waiting for a notification.  The <i>interrupted
       *             status</i> of the current thread is cleared when
@@ -489,9 +488,9 @@
       * description of the ways in which a thread can become the owner of
       * a monitor.
       *
-     * @exception  IllegalMonitorStateException  if the current thread 
is not
+     * @throws  IllegalMonitorStateException  if the current thread is not
       *               the owner of the object's monitor.
-     * @exception  InterruptedException if any thread interrupted the
+     * @throws  InterruptedException if any thread interrupted the
       *             current thread before or while the current thread
       *             was waiting for a notification.  The <i>interrupted
       *             status</i> of the current thread is cleared when
@@ -510,7 +509,7 @@
       * system resources or to perform other cleanup.
       * <p>
       * The general contract of {@code finalize} is that it is invoked
-     * if and when the Java<font size="-2"><sup>TM</sup></font> virtual
+     * if and when the Java™ virtual
       * machine has determined that there is no longer any
       * means by which this object can be accessed by any thread that has
       * not yet died, except as a result of an action taken by the
@@ -549,6 +548,9 @@
       * ignored.
       *
       * @throws Throwable the {@code Exception} raised by this method
+     * @see java.lang.ref.WeakReference
+     * @see java.lang.ref.PhantomReference
+     * @jls 12.6 Finalization of Class Instances
       */
      protected void finalize() throws Throwable { }
  }