Update documentation on Symbol. Make validation match.

sdk/lib/core/symbol.dart

Index: sdk/lib/core/symbol.dart
diff --git a/sdk/lib/core/symbol.dart b/sdk/lib/core/symbol.dart
index c92001af498dd2c8ffdff3761f09cfc16965311a..86709920fc8152c664528e92fe02f134bf22f74c 100644
--- a/sdk/lib/core/symbol.dart
+++ b/sdk/lib/core/symbol.dart
@@ -9,10 +9,19 @@ class Symbol {
   /**
    * Constructs a new Symbol.
    *
-   * An [ArgumentError] is thrown if [name] starts with an underscore, or if
-   * [name] is not a [String].  An [ArgumentError] is thrown if [name] is not
-   * an empty string and is not a valid qualified identifier optionally
-   * followed by [:'=':].
+   * The name must be a valid public Dart member name,
+   * public constructor name, or library name.
+   * That means that the content of the [name] String must be either
+   *
+   * * a valid Dart identifier not starting with "`_`",
+   * * such an identifier followed by "=" (a setter name),
+   * * or the name of an operator
+   *   (one of "`+`", "`-`", "`*`", "`/`", "`%`", "`~/`", "`&`", "`|`",
+   *   "`^`", "`~`", "`<<`", "`>>`", "`<`", "`<=`", "`>`", "`>=`", "`==`",
+   *   "`[]`", "`[]=`", or "`unary-`"),
+   * * The empty string (the default constructor name), or
+   * * A '`.`' separated sequence of identifiers (a library name). This must
+   *   also not begin with an underscore ("`_`").

[floitsch, 2014/01/31 14:37:24]

Why is _foo.bar not allowed, but foo._bar is?

[Lasse Reichstein Nielsen, 2014/01/31 18:19:26]

Because I saw no need to disallow foo._bar.
The problem is the interpretation of "_foo".
If it is a "declaration name", it is private.
If it is a library name, is it private or not?
It's hard to distinguish, so we disallow library names that start with '_'.
Underscores later are not a problem, because it is obviously a library name. I
can easily disallow them if it's a problem.
We could even allow underscores at the beginning if there is a '.' in there, but
I didn't want to complicate stuff even more.

[ahe, 2014/02/13 21:56:54]

I don't think this is correct, and I look forward to talking through this with
you in person. I'll be back in AAR Tue or Wed (depending on jet-lag).

    *
    * The following text is non-normative:
    *