Here, as an example, is a version of the source code for the class Object of the
package java.lang, including its documentation comments.
/* * @(#)Object.java 1.37 96/06/26 * * Copyright (c) 1994, 1995, 1996 Sun Microsystems, Inc. * All Rights Reserved. * * Permission to use, copy, modify, and distribute this * software and its documentation for NON-COMMERCIAL purposes * and without fee is hereby granted provided that this * copyright notice appears in all copies. Please refer to * the file "copyright.html" for further important copyright * and licensing information. * * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE * SUITABILITY OF THE SOFTWARE, EITHER EXPRESS OR IMPLIED, * INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR * NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR * DISTRIBUTING THIS SOFTWARE OR ITS DERIVATIVES. */
package java.lang;
/** * The root of the Class hierarchy. Every Class in the * system has Object as its ultimate parent. Every variable * and method defined here is available in every Object. * @see Class * @version 1.37, 26 Jun 1996 */
public class Object { /** * Returns the Class of this Object. Java has a runtime * representation for classes--a descriptor of type Class * --which the method getClass() returns for any Object. */ public final native Class getClass();
/** * Returns a hashcode for this Object. * Each Object in the Java system has a hashcode. * The hashcode is a number that is usually different * for different Objects. It is used when storing Objects * in hashtables. * Note: hashcodes can be negative as well as positive. * @see java.util.Hashtable */ public native int hashCode();
/** * Compares two Objects for equality. * Returns a boolean that indicates whether this Object * is equivalent to the specified Object. This method is * used when an Object is stored in a hashtable. * @param obj the Object to compare with * @return true if these Objects are equal; * false otherwise. * @see java.util.Hashtable */ public boolean equals(Object obj) { return (this == obj); }
/** * Creates a clone of the object. A new instance is * allocated and a bitwise clone of the current object * is placed in the new object. * @return a clone of this Object. * @exception OutOfMemoryError If there is not enough * memory. * @exception CloneNotSupportedException Object * explicitly does not want to be * cloned, or it does not support * the Cloneable interface. */ protected native Object clone() throws CloneNotSupportedException;
/**
* Returns a String that represents this Object.
* It is recommended that all subclasses override
* this method.
*/
public String toString() {
return getClass().getName() + "@" +
Integer.toHexString(hashCode());
}
/**
* Notifies a single waiting thread on a change in
* condition of another thread. The thread effecting
* the change notifies the waiting thread using notify().
* Threads that want to wait for a condition to change
* before proceeding can call wait(). <p>
* <em>The method notify() can be called only by the
* thread that is the owner of the current object's
* monitor lock.</em>
*
* @exception IllegalMonitorStateException If the
* current thread is not the owner
* of the Object's monitor lock.
* @see Object#wait
* @see Object#notifyAll
*/
public final native void notify();
/**
* Notifies all the threads waiting for a condition to
* change. Threads that are waiting are generally waiting
* for another thread to change some condition. Thus, the
* thread effecting a change that more than one thread is
* waiting for notifies all the waiting threads using
* the method notifyAll(). Threads that want to wait for
* a condition to change before proceeding can call
* wait(). <p>
* <em>The method notifyAll() can be called only by the
* thread that is the owner of the current object's
* monitor lock.</em>
*
* @exception IllegalMonitorStateException If the
* current thread is not the owner
* of the Object's monitor lock.
* @see Object#wait
* @see Object#notify
*/
public final native void notifyAll();
/** * Causes a thread to wait until it is notified or the * specified timeout expires. <p> * <em>The method wait(millis) can be called only by * the thread that is the owner of the current object's * monitor lock.</em> * * @param millis the maximum time to wait, * in milliseconds * @exception IllegalMonitorStateException If the * current thread is not the owner * of the Object's monitor lock. * @exception InterruptedException Another thread has * interrupted this thread. */ public final native void wait(long millis) throws InterruptedException;
/** * More accurate wait. * <em>The method wait(millis, nanos) can be called only * by the thread that is the owner of the current * object's monitor lock.</em> * * @param millis the maximum time to wait, * in milliseconds * @param nano additional time to wait, * in nanoseconds * (range 0-999999) * @exception IllegalMonitorStateException If the * current thread is not the owner * of the Object's monitor lock. * @exception InterruptedException Another thread has * interrupted this thread. */ public final void wait(long millis, int nanos) throws InterruptedException { if (nanos >= 500000 || (nanos != 0 && millis==0)) timeout++; wait(timeout); }
/** * Causes a thread to wait forever until it is notified. * <p> * <em>The method wait() can be called only by the * thread that is the owner of the current object's * monitor lock.</em> *
* @exception IllegalMonitorStateException If the
* current thread is not the owner
* of the Object's monitor lock.
* @exception InterruptedException Another thread has
* interrupted this thread.
*/
public final void wait() throws InterruptedException {
wait(0);
}
/**
* Code to perform when this object is garbage collected.
* The default is that nothing needs to be performed.
*
* Any exception thrown by a finalize method causes the
* finalization to halt. But otherwise, it is ignored.
*/
protected void finalize() throws Throwable { }
}
From this source code, the javadoc tool produced the following HTML file,
which is available for browsing at
http://java.sun.com/Series/, our Java
Series web site:
<!-- Generated by javadoc on Wed Jun 26 11:40:38 EDT 1996 -->
<a href="packages.html">All Packages</a> <a href="tree.html">Class Hierarchy¬
</a> <a href="Package-java.lang.html">This Package</a> <a href="java.lang.N¬
umber.html#_top_">Previous</a> <a href="java.lang.OutOfMemoryError.html#_top¬
_">Next</a> <a href="AllNames.html">Index</a></pre><dt> public class <b>Object</b>
The root of the Class hierarchy. Every Class in the
system has Object as its ultimate parent. Every variable
and method defined here is available in every Object.
<dd> <a href="java.lang.Class.html#_top_">Class</a>
<img src="images/constructor-index.gif" width=275 height=38 alt="Constructo¬
r Index"><dt> <img src="images/yellow-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#Object()"><b>Object</b></a>()
<img src="images/method-index.gif" width=207 height=38 alt="Method Index">
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#clone()"><b>clone</b></a>()
<dd> Creates a clone of the object.
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#equals(java.lang.Object)"><b>equals</b></a>(Object)
<dd> Compares two Objects for equality.
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#finalize()"><b>finalize</b></a>()
<dd> Code to perform when this object is garbage collected.
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#getClass()"><b>getClass</b></a>()
<dd> Returns the Class of this Object.
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#hashCode()"><b>hashCode</b></a>()
<dd> Returns a hashcode for this Object.
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#notify()"><b>notify</b></a>()
<dd> Notifies a single waiting thread on a change in
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#notifyAll()"><b>notifyAll</b></a>()
<dd> Notifies all the threads waiting for a condition to
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#toString()"><b>toString</b></a>()
<dd> Returns a String that represents this Object.
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#wait()"><b>wait</b></a>()
<dd> Causes a thread to wait forever until it is notified.
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#wait(long)"><b>wait</b></a>(long)
<dd> Causes a thread to wait until it is notified or the
<dt> <img src="images/red-ball-small.gif" width=6 height=6 alt=" o ">
<a href="#wait(long, int)"><b>wait</b></a>(long, int)
<img src="images/constructors.gif" width=231 height=38 alt="Constructors">
<a name="Object()"><img src="images/yellow-ball.gif" width=12 height=12 alt="¬
o "></a><img src="images/methods.gif" width=151 height=38 alt="Methods">
<a name="getClass()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a><a name="getClass"><b>getClass</b></a>
public final <a href="java.lang.Class.html#_top_">Class</a> getClass()
<dd> Returns the Class of this Object. Java has a runtime
representation for classes--a descriptor of type Class
--which the method getClass() returns for any Object.
<a name="hashCode()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a><a name="hashCode"><b>hashCode</b></a>
<dd> Returns a hashcode for this Object.
Each Object in the Java system has a hashcode.
The hashcode is a number that is usually different
for different Objects. It is used when storing Objects
Note: hashcodes can be negative as well as positive.
<dd> <a href="java.util.Hashtable.html#_top_">Hashtable</a>
<a name="equals(java.lang.Object)"><img src="images/red-ball.gif" width=12 he¬
ight=12 alt=" o "></a><a name="equals"><b>equals</b></a>
public boolean equals(<a href="#_top_">Object</a> obj)
<dd> Compares two Objects for equality.
Returns a boolean that indicates whether this Object
is equivalent to the specified Object. This method is
used when an Object is stored in a hashtable.
<dd> obj - the Object to compare with
<dd> true if these Objects are equal;
<dd> <a href="java.util.Hashtable.html#_top_">Hashtable</a>
<a name="clone()"><img src="images/red-ball.gif" width=12 height=12 alt=" o "¬
></a><a name="clone"><b>clone</b></a>
protected <a href="#_top_">Object</a> clone() throws <a href="java.lang.Clo¬
neNotSupportedException.html#_top_">CloneNotSupportedException</a><dd> Creates a clone of the object. A new instance is
allocated and a bitwise clone of the current object
<dt> <b>Throws:</b> <a href="java.lang.OutOfMemoryError.html#_top_">OutOf¬
MemoryError</a><dt> <b>Throws:</b> <a href="java.lang.CloneNotSupportedException.html#_t¬
op_">CloneNotSupportedException</a>explicitly does not want to be
cloned, or it does not support
<a name="toString()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a><a name="toString"><b>toString</b></a>
public <a href="java.lang.String.html#_top_">String</a> toString()
<dd> Returns a String that represents this Object.
It is recommended that all subclasses override
<a name="notify()"><img src="images/red-ball.gif" width=12 height=12 alt=" o ¬
"></a><a name="notify"><b>notify</b></a>
<dd> Notifies a single waiting thread on a change in
condition of another thread. The thread effecting
the change notifies the waiting thread using notify().
Threads that want to wait for a condition to change
before proceeding can call wait(). <p>
<em>The method notify() can be called only by the
thread that is the owner of the current object's
<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>current thread is not the owner
<dd> <a href="#wait">wait</a>, <a href="#notifyAll">notifyAll</a>
<a name="notifyAll()"><img src="images/red-ball.gif" width=12 height=12 alt="¬
o "></a><a name="notifyAll"><b>notifyAll</b></a>
<dd> Notifies all the threads waiting for a condition to
change. Threads that are waiting are generally waiting
for another thread to change some condition. Thus, the
thread effecting a change that more than one thread is
waiting for notifies all the waiting threads using
the method notifyAll(). Threads that want to wait for
a condition to change before proceeding can call
<em>The method notifyAll() can be called only by the
thread that is the owner of the current object's
<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>current thread is not the owner
<dd> <a href="#wait">wait</a>, <a href="#notify">notify</a>
<a name="wait(long)"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a><a name="wait"><b>wait</b></a>
public final void wait(long millis) throws <a href="java.lang.InterruptedEx¬
ception.html#_top_">InterruptedException</a><dd> Causes a thread to wait until it is notified or the
specified timeout expires. <p>
<em>The method wait(millis) can be called only by
the thread that is the owner of the current object's
<dd> millis - the maximum time to wait,
<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>current thread is not the owner
<dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a><a name="wait(long, int)"><img src="images/red-ball.gif" width=12 height=12 a¬
lt=" o "></a><a name="wait"><b>wait</b></a>
public final void wait(long millis,
int nanos) throws <a href="java.lang.InterruptedExce¬
ption.html#_top_">InterruptedException</a><em>The method wait(millis, nanos) can be called only
by the thread that is the owner of the current
<dd> millis - the maximum time to wait,
<dd> nano - additional time to wait,
<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>current thread is not the owner
<dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a><a name="wait()"><img src="images/red-ball.gif" width=12 height=12 alt=" o ">¬
</a><a name="wait"><b>wait</b></a>
public final void wait() throws <a href="java.lang.InterruptedException.htm¬
l#_top_">InterruptedException</a><dd> Causes a thread to wait forever until it is notified.
<em>The method wait() can be called only by the
thread that is the owner of the current object's
<dt> <b>Throws:</b> <a href="java.lang.IllegalMonitorStateException.html#¬
_top_">IllegalMonitorStateException</a>current thread is not the owner
<dt> <b>Throws:</b> <a href="java.lang.InterruptedException.html#_top_">I¬
nterruptedException</a><a name="finalize()"><img src="images/red-ball.gif" width=12 height=12 alt=" ¬
o "></a><a name="finalize"><b>finalize</b></a>
protected void finalize() throws <a href="java.lang.Throwable.html#_top_">T¬
hrowable</a><dd> Code to perform when this object is garbage collected.
The default is that nothing needs to be performed.
Any exception thrown by a finalize method causes the
finalization to halt. But otherwise, it is ignored.
<a href="packages.html">All Packages</a> <a href="tree.html">Class Hierarchy¬
</a> <a href="Package-java.lang.html">This Package</a> <a href="java.lang.N¬
umber.html#_top_">Previous</a> <a href="java.lang.OutOfMemoryError.html#_top¬
_">Next</a> <a href="AllNames.html">Index</a></pre></html>
Many of the lines in this HTML file are far too long to fit onto these
pages. We have used the character "¬" at the end of
a line to indicate that the following line
of text on the page is part of the same line in the generated file.
This generated HTML file is meant only as an example, not as a specification of the behavior of the javadoc tool, which may be changed over time to improve the HTML presentation of the documentation information.
Very few facts are able to tell their own story,
without comments to bring out their meaning.
—John Stuart Mill, On Liberty (1869)