diff options
| -rw-r--r-- | src/compiler/scala/tools/nsc/doc/ModelAdditions.scala | 213 | ||||
| -rw-r--r-- | src/compiler/scala/tools/nsc/symtab/Definitions.scala | 11 | ||||
| -rw-r--r-- | src/compiler/scala/tools/nsc/symtab/StdNames.scala | 1 |
3 files changed, 216 insertions, 9 deletions
diff --git a/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala b/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala index 0a373c509a..263d855b28 100644 --- a/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala +++ b/src/compiler/scala/tools/nsc/doc/ModelAdditions.scala @@ -7,7 +7,7 @@ package scala.tools.nsc.doc /** - * @author Stephane Micheloud, Sean McDirmid + * @author Stephane Micheloud, Sean McDirmid, Geoffrey Washburn * @version 1.0 */ class ModelAdditions(val global: Global) { @@ -55,6 +55,9 @@ class ModelAdditions(val global: Global) { type <a href="Int.html"><code>Int</code></a>. </p>""" + /*******************************************************************/ + /* Documentation for Any */ + addition(AnyClass); comments(AnyClass) = """ <p> @@ -68,33 +71,131 @@ class ModelAdditions(val global: Global) { <a href="AnyVal.html"><code>AnyVal</code></a>. </p>""" + addition(Any_equals); + comments(Any_equals) = """ + This method is used to compare the receiver object (<code>this</code>) + with the argument object (<code>arg0</code>) for equivalence. + + <p> + The default implementations of this method is an <a + href="http://en.wikipedia.org/wiki/Equivalence_relation">equivalence + relation</a>: + <ul> + <li>It is reflexive: for any instance <code>x</code> of type <code>Any</code>, + <code>x.eq(x)</code> should return <code>true</code>.</li> + <li>It is symmetric: for any instances <code>x</code> and <code>y</code> of type + <code>Any</code>, <code>x.eq(y)</code> should return <code>true</code> if and only + if <code>y.eq(x)</code> returns <code>true</code>.</li> + <li>It is transitive: for any instances + <code>x</code>, <code>y</code>, and <code>z</code> of type <code>AnyRef</code> + if <code>x.eq(y)</code> returns <code>true</code> and + <code>y.eq(z)</code> returns + <code>true</code>, then <code>x.eq(z)</code> should return <code>true</code>.</li> + </ul> + </p> + + <p> + If you override this method, you should verify that + your implementation remains an equivalence relation. + Additionally, when overriding this method it is often necessary to + override <code>hashCode</code> to ensure that objects that are + "equal" (<code>o1.equals(o2)</code> returns <code>true</code>) + hash to the same <a href="Int.html"><code>Int</code></a> + (<code>o1.hashCode.equals(o2.hashCode)</code>). + + @param arg0 the object to compare against this object for equality. + @return <code>true</code> if the receiver object is equivalent to the argument; <code>false</code> otherwise. + </p> + """ + addition(Any_==); comments(Any_==) = """ + <code> o == arg0</code> is the same as <code>o.equals(arg0)</code>. <p> - <code> o1 == o2</code> is the same as <code>o1.equals(o2)</code>. + @param arg0 the object to compare against this object for equality. + @return <code>true</code> if the receiver object is equivalent to the argument; <code>false</code> otherwise. </p> """ addition(Any_!=); comments(Any_!=) = """ + <code> o != arg0</code> is the same as <code>!(o.equals(arg0))</code>. <p> - <code> o1 != o2</code> is the same as <code>!(o1.equals(o2))</code>. + @param arg0 the object to compare against this object for dis-equality. + @return <code>false</code> if the receiver object is equivalent to the argument; <code>true</code> otherwise. </p> """ addition(Any_toString); comments(Any_toString) = """ - <p> Returns a string representation of the object. + <p> + The default representation is platform dependent. + + @return a string representation of the object. </p> """ + addition(Any_asInstanceOf); + comments(Any_asInstanceOf) = """ + This method is used to cast the receiver object to be of type <code>T0</code>. + + <p>Note that the success of a cast at runtime is modulo Scala's + erasure semantics. Therefore the expression + <code>1.asInstanceOf[String]</code> will throw a + <code>ClassCastException</code> at runtime, while the expression + <code>List(1).asInstanceOf[List[String]]</code> will not. In the + latter example, because the type argument is erased as part of + compilation it is not possible to check whether the contents of + the list are of the requested typed. + + @throws ClassCastException if the receiver object is not an + instance of erasure of type <code>T0</code>. + @return the receiver object. + </p> """ + + addition(Any_isInstanceOf); + comments(Any_isInstanceOf) = """ + This method is used to test whether the dynamic type of the receiver object is <code>T0</code>. + + <p>Note that the test result of the test is modulo Scala's erasure + semantics. Therefore the expression + <code>1.isInstanceOf[String]</code> will return + <code>false</code>, while the expression + <code>List(1).isInstanceOf[List[String]]</code> will return + <code>true</code>. In the latter example, because the type + argument is erased as part of compilation it is not possible to + check whether the contents of the list are of the requested typed. + + @return <code>true</code> if the receiver object is an + instance of erasure of type <code>T0</code>; <code>false</code> otherwise. + """ + addition(Any_hashCode); comments(Any_hashCode) = """ - <p> Returns a hash code value for the object. + + <p> + The default hashing algorithm is platform dependent. + + Note that it is allowed for two objects to have identical hash + codes (<code>o1.hashCode.equals(o2.hashCode)</code>) yet not be + equal (<code>o1.equals(o2)</code> returns <code>false</code>). A + degenerate implementation could always return <code>0</code>. + However, it is required that if two objects are equal + (<code>o1.equals(o2)</code> returns <code>true</code>) that they + have identical hash codes + (<code>o1.hashCode.equals(o2.hashCode)</code>). Therefore, when + overriding this method, be sure to verify that the behavior is + consistent with the <code>equals</code> method. </p> - """ + + <p> + @return the hash code value for the object. + </p> """ + + /*******************************************************************/ + /* Documentation for AnyRef */ addition(AnyRefClass); comments(AnyRefClass) = """ @@ -103,6 +204,106 @@ class ModelAdditions(val global: Global) { <em>reference types</em>. </p>""" + addition(Object_ne); + comments(Object_ne) = """ + <code> o.ne(arg0)</code> is the same as <code>!(o.ne(arg0))</code>. + <p> + @param arg0 the object to compare against this object for reference dis-equality. + @return <code>false</code> if the argument is not a reference to the receiver object; <code>true</code> otherwise. + </p> + """ + + + addition(Object_finalize); + comments(Object_finalize) = """ + This method is called by the garbage collector on the receiver object when garbage + collection determines that there are no more references to the object. + <p> + The details of when and if the <code>finalize</code> method are + invoked, as well as the interaction between <code>finalize</code> + and non-local returns and exceptions, are all platform dependent. + </p> + """ + + addition(Object_clone); + comments(Object_clone) = """ + This method creates and returns a copy of the receiver object. + + <p> + The default implementation of the <code>clone</code> method is platform dependent. + + @return a copy of the receiver object. + </p> + """ + + addition(Object_getClass); + comments(Object_getClass) = """ + Returns a representation that corresponds to the dynamic class of the receiver object. + + <p> + The nature of the representation is platform dependent. + + @return a representation that corresponds to the dynamic class of the receiver object. + </p> + """ + + addition(Object_notify); + comments(Object_notify) = """ + Wakes up a single thread that is waiting on the receiver object's monitor. + """ + + addition(Object_notifyAll); + comments(Object_notifyAll) = """ + Wakes up all threads that are waiting on the receiver object's monitor. + """ + + addition(Object_eq); + comments(Object_eq) = """ + This method is used to test whether the argument (<code>arg0</code>) is a reference to the + receiver object (<code>this</code>). + + <p> + The <code>eq</code> method implements an + <a href="http://en.wikipedia.org/wiki/Equivalence_relation">equivalence relation</a> on non-null instances of + <code>AnyRef</code>: + <ul> + <li>It is reflexive: for any non-null instance <code>x</code> of type <code>AnyRef</code>, + <code>x.eq(x)</code> returns <code>true</code>.</li> + <li>It is symmetric: for any non-null instances <code>x</code> and <code>y</code> of type + <code>AnyRef</code>, <code>x.eq(y)</code> returns <code>true</code> if and only + if <code>y.eq(x)</code> returns <code>true</code>.</li> + <li>It is transitive: for any non-null instances + <code>x</code>, <code>y</code>, and <code>z</code> of type <code>AnyRef</code> + if <code>x.eq(y)</code> returns <code>true</code> and + <code>y.eq(z)</code> returns + <code>true</code>, then <code>x.eq(z)</code> returns <code>true</code>.</li> + </ul> + Additionally, the <code>eq</code> method has three other properties. + <ul> + <li>It is consistent: for any non-null instances <code>x</code> and <code>y</code> of type <code>AnyRef</code>, + multiple invocations of <code>x.eq(y)</code> consistently returns <code>true</code> + or consistently returns <code>false</code>.</li> + <li>For any non-null instance <code>x</code> of type <code>AnyRef</code>, + <code>x.eq(null)</code> and <code>null.eq(x)</code> returns <code>false</code>.</li> + <li><code>null.eq(null)</code> returns <code>true</code>.</li> + </ul> + </p> + + <p> When overriding the <code>equals</code> or + <code>hashCode</code> methods, it is important to ensure that + their behavior is consistent with reference equality. Therefore, + if two objects are references to each other (<code>o1 eq + o2</code>), they should be equal to each other (<code>o1 == + o2</code>) and they should hash to the same value + (<code>o1.hashCode == o2.hashCode</code>).</p> + + @param arg0 the object to compare against this object for reference equality. + @return <code>true</code> if the argument is a reference to the receiver object; <code>false</code> otherwise. + </p> + """ + + /*******************************************************************/ + addition(AnyValClass); comments(AnyValClass) = """ <p> diff --git a/src/compiler/scala/tools/nsc/symtab/Definitions.scala b/src/compiler/scala/tools/nsc/symtab/Definitions.scala index 450a03993f..18fd09e0ba 100644 --- a/src/compiler/scala/tools/nsc/symtab/Definitions.scala +++ b/src/compiler/scala/tools/nsc/symtab/Definitions.scala @@ -282,9 +282,14 @@ trait Definitions { var Object_synchronized: Symbol = _ var Object_isInstanceOf: Symbol = _ var Object_asInstanceOf: Symbol = _ - def Object_equals = getMember(ObjectClass, nme.equals_) - def Object_hashCode = getMember(ObjectClass, nme.hashCode_) - def Object_toString = getMember(ObjectClass, nme.toString_) + def Object_getClass = getMember(ObjectClass, nme.getClass_) + def Object_clone = getMember(ObjectClass, nme.clone_) + def Object_finalize = getMember(ObjectClass, nme.finalize_) + def Object_notify = getMember(ObjectClass, nme.notify_) + def Object_notifyAll = getMember(ObjectClass, nme.notifyAll_) + def Object_equals = getMember(ObjectClass, nme.equals_) + def Object_hashCode = getMember(ObjectClass, nme.hashCode_) + def Object_toString = getMember(ObjectClass, nme.toString_) var String_+ : Symbol = _ diff --git a/src/compiler/scala/tools/nsc/symtab/StdNames.scala b/src/compiler/scala/tools/nsc/symtab/StdNames.scala index de08a7ef66..aa8b0710fa 100644 --- a/src/compiler/scala/tools/nsc/symtab/StdNames.scala +++ b/src/compiler/scala/tools/nsc/symtab/StdNames.scala @@ -349,6 +349,7 @@ trait StdNames { val tail = newTermName("tail") val toList = newTermName("toList") val toString_ = newTermName("toString") + val clone_ = newTermName("clone") val that = newTermName("that") val that1 = newTermName("that1") val this_ = newTermName("this") |