Add documentation to the Object class in the core library.

lib/core/object.dart

Index: lib/core/object.dart
diff --git a/lib/core/object.dart b/lib/core/object.dart
index 2d09bf45c1debdeb76fc53e175f86bbfbf573b29..544c2c486ce8bdd5d38abc6fb70658d8bd84f7a9 100644
--- a/lib/core/object.dart
+++ b/lib/core/object.dart
@@ -6,19 +6,62 @@
  * Everything in Dart is an [Object].
  */
 class Object {
+  /**
+   * Object constructor.

[Lasse Reichstein Nielsen, 2012/09/24 10:43:18]

That's obvious. This constructor is only here because it's const, otherwise it
would have been implicit. So instead document when you would use it ...
something like:
/**
 * Creates a new [Object] instance.
 *
 * [Object] instances have no meaningful state, and are only
 * useful through their identity. An [Object] instance is  
 * equal to itself only, and not to any other object.
 */
?

[Mads Ager (google), 2012/09/24 11:07:15]

Done, thanks.

+   */
   const Object();
 
+  /**
+   * The equality operator.

[Lasse Reichstein Nielsen, 2012/09/24 10:43:18]

We'll probably want to add something about equivalence relations here, but this
is great for now!

+   *
+   * The default behavior for all [Object]s is to return true if and
+   * only if [:this:] and [other] are the same object.
+   *
+   * If a subclass overrides the equality operator it should override
+   * the [hashCode] method as well to maintain consistency.
+   */
   bool operator ==(other) => identical(this, other);
 
+  /**
+   * Get a hash code for this object.
+   *
+   * All objects have hash codes. Hash codes are guaranteed to be the
+   * same for objects that are equal when compared using the equality
+   * operator [:==:]. Other than that there are no guarantees about
+   * the hash codes. They will not be consistent between runs and
+   * there are no distribution guarantees.

[Lasse Reichstein Nielsen, 2012/09/24 10:43:18]

I really want to promise that hash-codes are 32-bit unsigned integers (which is
kind-of a distribution guarantee - it rules out the really stupid
implementations like what we have for double). Do you see any problems with
going that way?

[Mads Ager (google), 2012/09/24 11:07:15]

I don't see a problem with using 32-bit unsigned integers for the default hash
codes. However, since the language has no concept of 32-bit unsigned integers I
don't think it makes sense to add a comment to that effect.

+   *
+   * If a subclass overrides [hashCode] it should override the
+   * equality operator as well to maintain consistency.
+   */
   external int hashCode();
 
+  /**
+   * Returns a string representation of this object.
+   */
   external String toString();
 
+  /**
+   * [noSuchMethod] is invoked when users invoke a non-existant method
+   * on an object. The name of the method and the arguments of the
+   * invocation are passed to [noSuchMethod]. If [noSuchMethod]
+   * returns a value, that value becomes the result of the original
+   * invocation.
+   *
+   * The default behavior of [noSuchMethod] is to throw a
+   * [noSuchMethodError].
+   */
   external void noSuchMethod(String name, List args);

[Mads Ager (google), 2012/09/24 10:13:13]

The void return type is confusing here. Should we change it to Object?

[Lasse Reichstein Nielsen, 2012/09/24 10:43:18]

If anything, we should change it to Dynamic. And yes, I think we should change
it. It's all equivalent for this implementation, since it always throws, but it
will set the style for people overriding noSuchMethod. (Remember to change
patches too).

[Mads Ager (google), 2012/09/24 11:07:15]

I have changed it to Dynamic.

 
+  /**
+   * Returns the representation of the runtime type of the object.

[Lasse Reichstein Nielsen, 2012/09/24 10:43:18]

the representation -> a representation.
We don't guarantee that it's the same object every time.

[Mads Ager (google), 2012/09/24 11:07:15]

Done.

+   */
   external Type runtimeType();
 }
 
+/**
+ * Representation of the runtime type of an object.

[Lasse Reichstein Nielsen, 2012/09/24 10:43:18]

Just "Representation of a type." You can get representations of non-instantiable
types too.

[Mads Ager (google), 2012/09/24 11:07:15]

Done.

+ */
 abstract class Type {}
 
 /**