Remove spec references to Symbol constructor.
Change-Id: I3c6fe9d27aad387a55f9a003d94faa6a9a72f227
Reviewed-on: https://dart-review.googlesource.com/44741
Commit-Queue: Lasse R.H. Nielsen <lrn@google.com>
Reviewed-by: Erik Ernst <eernst@google.com>
diff --git a/docs/language/dartLangSpec.tex b/docs/language/dartLangSpec.tex
index 502333c..ce1ff45 100644
--- a/docs/language/dartLangSpec.tex
+++ b/docs/language/dartLangSpec.tex
@@ -4053,7 +4053,8 @@
\LMLabel{symbols}
\LMHash{}
-A {\em symbol literal} denotes the name of a declaration in a Dart program.
+A {\em symbol literal} denotes a name that would be either
+a valid declaration name or a valid library name in a Dart program.
\begin{grammar}
{\bf symbolLiteral:}`\#' (operator $|$ (identifier (`{\escapegrammar .}' identifier)*))
@@ -4061,10 +4062,39 @@
\end{grammar}
\LMHash{}
-A symbol literal \code{\#\id} where \id{} does not begin with an underscore ('\code{\_}') is equivalent to the expression \code{\CONST{} Symbol('\id')}.
+A symbol literal \code{\#$id$} where $id$ is an identifier
+that does not begin with an underscore ('\code{\_}'),
+evaluates to an instance of \code{Symbol} representing the identifier $id$.
+All occurences of \code{\#$id$} evaluate to the same instance
+\commentary{(symbol instances are canonicalized)},
+and no other symbol literals evaluate to that \code{Symbol} instance
+or to a \code{Symbol} instance that is equal
+(according to the \code{==} operator \ref{equality}) to that instance.
\LMHash{}
-A symbol literal \code{\#\_\id} evaluates to the object that would be returned by the call \code{MirrorSystem.getSymbol("\_\id", \metavar{libraryMirror})} where \metavar{libraryMirror} is an instance of the class \code{LibraryMirror} defined in the library \code{dart:mirrors}, reflecting the current library.
+A symbol literal \code{\#$id$.$id_2$\ldots$id_n$}
+where $id$ \ldots $id_n$ are identifiers,
+evaluates to an instance of \code{Symbol} representing that particular sequence of identifiers.
+All occurences of \code{\#$id$.$id_2$\ldots$id_n$} with the same sequence of identifiers
+evaluate to the same instance,
+and no other symbol literals evaluate to that \code{Symbol} instance
+or to a \code{Symbol} instance that is \code{==} to that instance.
+\commentary{This kind of symbol literal denotes the name of a library declaration. Library names are not subject to library privacy, even
+if some of its identifiers begin with an underscore.}
+
+\LMHash{}
+A symbol literal \code{\#\metavar{operator}} evaluates to an instance of \code{Symbol}
+representing that particular operator name.
+All occurences of \code{\#\metavar{operator}} evaluate to the same instance,
+and no other symbol literals evaluate to that \code{Symbol} instance
+or to a \code{Symbol} instance that is \code{==} to that instance.
+
+\LMHash{}
+A symbol literal \code{\#\_$id$}, evaluates to an instance of \code{Symbol}
+representing the private identifier \code{_$id} of the containing library.
+All occurences of \code{\#\_$id$} {\em in the same library} evaluate to the same instance,
+and no other symbol literals evaluate to that \code{Symbol} instance
+or to a \code{Symbol} instance that is \code{==} to that instance.
\rationale{
One may well ask what is the motivation for introducing literal symbols? In some languages, symbols are canonicalized whereas strings are not.
@@ -4076,7 +4106,7 @@
This practice poses difficulties for reflective programs that refer to program declarations via strings.
A string will refer to an identifier in the source, but the identifier will no longer be used in the minified code, and reflective code using these would fail.
Therefore, Dart reflection uses objects of type \code{Symbol} rather than strings.
-Instances of \code{Symbol} are guaranteed to be stable with repeat to minification.
+Instances of \code{Symbol} are guaranteed to be stable with respect to minification.
Providing a literal form for symbols makes reflective code easier to read and write.
The fact that symbols are easy to type and can often act as convenient substitutes for enums are secondary benefits.
}
@@ -4084,7 +4114,6 @@
\LMHash{}
The static type of a symbol literal is \code{Symbol}.
-
\subsection{Lists}
\LMLabel{lists}
@@ -5605,14 +5634,7 @@
then if $g$ is a getter that forwards to a static getter, getter lookup fails.
If the getter lookup succeeded,
let $v_g$ be the value of the getter invocation $e.m$.
-Then the value of $i$ is the result of invoking the static method
-\code{Function.apply()}
-with arguments
-$v_g$,
-\code{[$o_1, \ldots, o_n$]},
-\code{\{$\#x_{n+1}$: $o_{n+1}, \ldots, \#x_{n+k}$: $o_{n+k}$\}},
-and
-\code{[$t_1, \ldots, t_r$]}.
+Now repeat from finding $f$ above, this time with $o$ being $v_g$ and $m$ being \code{call}.
\LMHash{}
If getter lookup has also failed,
@@ -5801,14 +5823,7 @@
then let $g$ be the result of looking up getter (\ref{getterAndSetterLookup}) $m$ in $S_{dynamic}$ with respect to $L$.
If the getter lookup succeeded,
let $v_g$ be the value of the getter invocation $\SUPER{}.m$.
-Then the value of $i$ is the result of invoking
-the static method
-\code{Function.apply()}
-with arguments
-$v_g,
-[o_1, \ldots, o_n],
-\{\#x_{n+1}: o_{n+1}, \ldots, \#x_{n+k}: o_{n+k}\},
-[t_1, \ldots, t_r]$.
+Now repeat from finding $f$ above, this time with $o$ being $v_g$ and $m$ being \code{call}.
\LMHash{}
If getter lookup has also failed,
diff --git a/sdk/lib/core/symbol.dart b/sdk/lib/core/symbol.dart
index ac0fc65..8580d6f 100644
--- a/sdk/lib/core/symbol.dart
+++ b/sdk/lib/core/symbol.dart
@@ -18,7 +18,7 @@
static const Symbol empty = const Symbol("");
/**
- * Constructs a new Symbol.
+ * Constructs a new [Symbol] representing the provided name.
*
* The name must be a valid public Dart member name,
* public constructor name, or library name, optionally qualified.
@@ -39,6 +39,37 @@
* * or the empty string (the default name of a library with no library
* name declaration).
*
+ * Symbol instances created from the same [name] are equal,
+ * but not necessarily identical, but symbols created as compile-time
+ * constants are canonicalized, as all other constant object creations.
+ *
+ * ```dart
+ * assert(new Symbol("foo") == new Symbol("foo"));
+ * assert(identical(const Symbol("foo"), const Symbol("foo")));
+ * ```
+ *
+ * If [name] is a single identifier that does not start with an underscore,
+ * or it is a qualified identifier,
+ * or it is an operator name different from `unary-`,
+ * then the result of `const Symbol(name)` is the same instance that
+ * the symbol literal created by prefixing `#` to the content of [name]
+ * would evaluate to.
+ *
+ * ```dart
+ * assert(new Symbol("foo") == #foo);
+ * assert(new Symbol("[]=") == #[]=]);
+ * assert(new Symbol("foo.bar") == #foo.bar);
+ * assert(identical(const Symbol("foo"), #foo));
+ * assert(identical(const Symbol("[]="), #[]=]));
+ * assert(identical(const Symbol("foo.bar"), #foo.bar));
+ * ```
+ *
+ * This constructor cannot create a [Symbol] instance that is equal to
+ * a private symbol literal like `#_foo`.
+ * ```dart
+ * const Symbol("_foo") // Invalid
+ * ``
+ *
* The following text is non-normative:
*
* Creating non-const Symbol instances may result in larger output. If
