Add documentation to the Object class in the core library.

Add documentation to the Object class in the core library.

R=lrn@google.com
BUG=

Committed: https://code.google.com/p/dart/source/detail?r=12770

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

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart
File lib/core/object.dart (right):

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode54
lib/core/object.dart:54: external void noSuchMethod(String name, List args);
The void return type is confusing here. Should we change it to Object?

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

LGTM!

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart
File lib/core/object.dart (right):

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode10
lib/core/object.dart:10: * Object constructor.
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.
 */
?

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode15
lib/core/object.dart:15: * The equality operator.
We'll probably want to add something about equivalence relations here, but this
is great for now!

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode32
lib/core/object.dart:32: * there are no distribution guarantees.
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?

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode54
lib/core/object.dart:54: external void noSuchMethod(String name, List args);
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).

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode57
lib/core/object.dart:57: * Returns the representation of the runtime type of the
object.
the representation -> a representation.
We don't guarantee that it's the same object every time.

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode63
lib/core/object.dart:63: * Representation of the runtime type of an object.
Just "Representation of a type." You can get representations of non-instantiable
types too.

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

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart
File lib/core/object.dart (right):

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode10
lib/core/object.dart:10: * Object constructor.
On 2012/09/24 10:43:18, Lasse Reichstein Nielsen wrote:
> 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.
>  */
> ?
> 

Done, thanks.

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode32
lib/core/object.dart:32: * there are no distribution guarantees.
On 2012/09/24 10:43:18, Lasse Reichstein Nielsen wrote:
> 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?

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.

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode54
lib/core/object.dart:54: external void noSuchMethod(String name, List args);
On 2012/09/24 10:43:18, Lasse Reichstein Nielsen wrote:
> 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).

I have changed it to Dynamic.

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode57
lib/core/object.dart:57: * Returns the representation of the runtime type of the
object.
On 2012/09/24 10:43:18, Lasse Reichstein Nielsen wrote:
> the representation -> a representation.
> We don't guarantee that it's the same object every time.

Done.

https://codereview.chromium.org/10974004/diff/1/lib/core/object.dart#newcode63
lib/core/object.dart:63: * Representation of the runtime type of an object.
On 2012/09/24 10:43:18, Lasse Reichstein Nielsen wrote:
> Just "Representation of a type." You can get representations of
non-instantiable
> types too.

Done.