Hi,
The attached are comments through section 10 of the April draft.
Some of it is miscellaneous suggestions for improvement in text that
already exists in the ES3 spec, and I understand that you might not want
to get too deep into those weeds this time around...
There are also some more substantive comments and corrections on the new
stuff (especially section 10).
I'll try to review the rest of the spec as time allows, but I wanted to
get this first batch of comments sent off today.
David Flanagan
4.2, 2nd paragraph: says that properties hold methods, then defines a
method as a function associated with an object via a property. I
think this is circular. And it doesn't mention that functions are a
kind of object.
4.2.1: "EcmaScript does not contain classes". Maybe choose a clearer
word that "contain". Also (and I think already mentioned by someone
else) I don't think there is any need to mention "allocates storage
for". More confusing than clarifying.
4.3: the definitions in the subsections that follow would be enhanced
by cross references to the sections that provide normative details.
4.3.6: The definition of a native object confuses me. It requires such
an object to be "supplied by an implementation" but allows it to be
"constructed during the course of execution of an ECMAScript program".
If native objects include objects created by user programs, then
"supplied by" is misleading. And if native objects refer to objects
created by some kind of prolog file executed at interpreter startup,
then "of an ECMAScript program" is misleading.
4.3.9 and 4.3.10: it is not explicitly stated that the undefined value
of 4.3.9 is the one member of type Undefined refered to in 4.3.10.
Ditto for 4.3.11 and 4.3.12.
4.3.11: this paragraph uses "reference", which is not
consistent with the "properties are containers" metaphor of 4.2.
4.3.15: this is the first time that "instance of" appears. I think it
would be useful to define it somewhere in 4.3
4.3.18: Confusing because it basically says "a string object is an
instance of the string object". Perhaps when using "instance of" you
could use the word "constructor" instead of object. This would be a
change throughout.
4.3.26: last line implies that functions are not objects.
5.1.2: s/clause/section/ in first line
5.1.4: s/clause/section/ in first line
5.1.7, middle of the 1st paragraph: "All nonterminal characters
specified in this way..." Shouldn't that be "All *terminal*
characters"?
5.1.7, near the bottom of page 9: "immediately following input
terminal". Wouldn't "token" be a clearer word than "terminal" here?
6, 1st paragraph: the requirement for UTF-16 puzzles me. I don't
understand what purpose it serves in the specification, and it might
lead readers to think that they have to transcode their HTML files to
UTF-16! I would think that it would be sufficient to say something
like "a conforming interpreter must treat string literals as if they
were encoded in UTF-16". Everything is probably correct as it stands
here, but it is probably confusing to all but real Unicode wizards.
7: It is unfortunate that one of the non-terminals (aka tokens) of
this lexical grammar is named "Token". This is confusing.
7.2: says that whitespace can appear in string literals but not other
tokens. This refers to the Token production, but it is confusing
because comments and regexps can contain whitespace as well... The
distinction between regexps and other "tokens" is an artificial one
anyway, so I think it would be clearer to list all non-terminals that
can contain whitespace...
7.3: same comment as above. Line terminators can occur in comments
and it is confusing that comments aren't considered "tokens".
7.5: The organization of the grammar gets strange here. It seems to
me that 7.6 should come before 7.5. 7.5 begins with a production for
identifiers, but then the body of the section defines reserved words,
with no indication that they are kinds of identifiers.
7.6, bottom of page 17: the HexDigit production is not needed here.
It belongs in 7.8.4
7.8.4, bottom of page 21: if you move HexDigit here, then cut the
cross-reference back to 7.6.
7.9: this is a really awkward paragraph--statements must be terminated
with semicolons, but the semicolons may be omitted.
8, 2nd paragraph: would it simplify things throughout the
specification if you formally defined Function as a subtype of Object?
8.6, 1st bullet point: either say "value and a set of boolean
attributes" or just a "set of attributes" since [[Value]] is defined
as an attribute on the next page.
8.6, 2nd bullet: method or function? These are called as methods, but
they're described as functions in the table on the next page.
8.6, 3rd bullet: cut "by the language specification". Also, since
we've just talked about an "accessor property", it is really confusing
to have the phrase "property accessor" appear here.
8.6.1, 1st table: change header of 2nd column to match the tables that
follow.
8.6.1, 2nd table: the descriptions of [[Get]] and [[Set]] should make
it clear that these are called as methods, even if they are described
as "functions".
8.6.1, bottom of page 29: Add "by this language specification" after
"is not explicitly specified". Otherwise, it sounds as if user code
must explicitly specify these attributes for each object property.
8.6.2, table 4: section number crossrefs to the varous SpecOp
definitions would be helpful.
8.12.9, 2nd to last paragraph, page 39. Change "O is a Date object" to
something like "O is an instance of the Date constructor".
8.12.10, algorithm step 10.b: is it intentional that a property value
can be changed even if [[Writable]] is false, as long as
[[Configurable]] is true? That makes sense, but I think it is worth
noting explicitly at the end of the section.
9.1: 1st and 2nd lines: these mention Value and value. I think both
ought to be lowercase and italics.
10.1.1: the first line refers to 4.2.2, which is non-normative. Is
that okay?
10.2.1, 1st para: cut "or variables"
10.2.1, 1st table, 3rd row. The description of this abstract version
of GetBindingValue does not describe the circumstances in which a
ReferenceError is thrown generally enough: it covers the DER case but
not the OER case.
In the 4th row of the table, change "strict mode references" to
"strict mode assignments"?
10.2.1.1, 2nd para: looks like there is an unwanted period after
"Declarative". Also, it would be nice if the subsections that follow
were in the same order as the rows of the table above.
10.2.1.1.2: this algorithm (and several that follow) inlude an
assertion. But you've never defined how assertions work in these
algorithms. Add something to section 5.2?
10.2.1.1.6: step 4 implies that a flag is necessary to distinguish an
uninitialized undefined from an initialized undefined. This is
confusing because the section right before also uses the word
"initialize" to describe the uninitialized undefined value. I
recommend recasting the description of DER so that each binding
includes a variable with three possible states: Mutable,
Immutable and UninitializedImmutable. Then algorithm steps can refer
explicitly to the variable and these values.
10.2.1.2: my first question in the first paragraph was whether OERs
worked with inherited properties or own properties only. Might be
worth making this clear right away. Also enumerable
vs. non-enumerable properties.
10.2.1.2.4, algorithm step 4: this doesn't match the abstract
description of this method in the table in 10.2.1.
10.2.2.2: I'd cut "Record" from the name of this function. It creates
an environment, not an environment record.
10.2.2.3: ditto. And also, why doesn't this function take an initial
value for providesThis?
10.5: I'd move this section so it comes after 10.6. The "may be
created" in the first line is vague. How about a cross reference to
the section that explains when it is created and when it isn't.
10.5, algorithm step 17.b and 17.c: these use the undefined identifier F. I
think it should be obj.
10.5: the MakeArgGetter and MakeArgSetter stuff seems like a kludge.
But I don't have anything better to propose.
10.5, 1st sentence of the note at the end of the section: I think I
read this algorithm pretty carefully, but it looks to me as if
numbered properties of the arguments object are handled completely
differently than named properties, and I can't see how they share
their values.
10.5, last para of the note at the end: the descriptions of
caller and callee are reversed. Callee is the standard property.
Caller is the extension.
10.6: 2nd paragraph defines func as an "input" to the algorithm, but
then algorithm 3a defines this same variable.
10.6: Change "Bind" to "Binding" in function names in steps 3.d.iv,
4.d, 7.b.ii, and 7.c.ii
10.6, step 4b: insert "section" before 13.
10.6, step 7.c.ii: Maybe change "strict" to false?
_______________________________________________
es-discuss mailing list
es-discuss@mozilla.org
https://mail.mozilla.org/listinfo/es-discuss
