Re: [WebIDL] feedback document posted

On Aug 23, 2011, at 1:19 AM, Anne van Kesteren wrote:

> Could you please email it to the list (preferably plain text) so it is publicly archived here?

Comments on WebIDL draft dated July 12, 2011
Allen Wirfs-Brock
Ecma TC39 ECMA-262 Project Editor

Where is the meaning of green, grey, and blue backgrounds defined?

Clause 2

It isn’t clear to me that the phrase “conforming <language> implementation” has any real utility relative to any specific WebIDL fragment. It apparently means that the language binding works as specified for that API fragment but it doesn’t necessarily mean that the actual functionality accessed through that API is conforms to its corresponding specification. 

The two actual uses of “conforming ECMAScript implementation” in this specification seem redundant. The usage in the first paragraph of clause 4 is essentially a restatement of the definition from clause 2. The only other usage in the first paragraph of 4.1 is unnecessary as it has already been established that clause 4 defines the behavior of a conforming ECMAScript implementation.  The usages of “conforming Java implementation” seem to be similarly insignificant.

My sense is that the definition of conformance in clause 2 may be appropriate but the current usage of the phrases in in clauses 4 and 5 are unnecessary and perhaps  undesirable as the usagr isappears relative to only a couple specific requirements when in fact all of the requirements of these clauses are necessary for conformance. 

Clause 3, paragraph 1
“describe the interfaces (in the object-oriented sense)”  what is the “object-oriented sense” and who defines its. For example, see 

Clause 3 Example

Because this section is, in theory, independent of any specific language binding, I wonder if it is really appropriate to only talk about the ECMAScript binding in the example.  It would clarify that this is a language independent interface definition if the paragraphs describing the ECMAScript binding of the example module were immediately followed by paragraphs about  the Java binding. 

Clause 3.1

“For constants, ... the final identifier token before the semicolon at the end of the declaration determines the identifier.”
but in: 
const type constant-identifier = value;
the value  may be one of the identifiers “true”, “false”, or “null” so the above statement is not always correct.

Clause 3.1
“The qualified name of every module, interface, dictionary, exception and typedef MUST NOT be the same as the qualified name of any other interface, dictionary, exception or typedef. ”

in what context?  All WebIDL code that is ever written.  Within a single specification? Among all W3G specifications?  Implicitly, what outer-most scope are you talking about in relationship to this statement.

Clause 3.2 Modules

I appreciate the desire to eliminate modules, if they are currently being used by any specifications.  However, this also seems short sighted.  In ECMA TC39 we generally try to be very conservative in adding new names to the global name space (ie, properties of the global object) because of the high probability that such names will clash with user defined global names used by existing web pages.  To the extend that WebIDL names are converted to global ECMAScript names (for example, interface names manifesting as ECMAScript constructor functions), WebIDL and W3C specification have the same problem. Some sort of  name space qualification of  global names introduced by W3C  specifications seems essential. If it isn’t accomplished via WebIDL modules it needs to be specified in some other manner.

Clause 3.3 Interfaces
First paragraph: “An interface is a definition (matching Interface) that defines an interface that objects in the system can implement. ”

This definition seems highly circular.  “An interface is a definition … that defines an interface...”
What definition applies to the second occurrence of “interface”?  Also this seems to be the first normative use of “object(s)” and it does not have a definition. What is an “object”.  This is important because subsequent paragraphs make various assertions about objects within any language binding qualification.  How does the WebIDL concept of “object” relative to specific language bindings and the rules and capabilities of those languages?

Third paragraph: “Objects implementing the interface will have members”.  What is an object “member”?

It isn’t clear whether or not an interface definition can specify a member with the same name as an inherited member and if so, what meaning is applied to such definitions. 

“Note that general multiple inheritance of interfaces is not supported, and <<1:objects also cannot implement arbitrary sets of interfaces>>. <<2: Objects can be defined to implement a single given interface A, which means that it also implements all of A’s inherited interfaces. In addition, an implements statement can be used to define that objects implementing ane interface will always also implement another interface. >>”

<<1>> In what ways is this intended to restrict actual language objects?  Does it mean that langauge objects that implement a WebIDL interface may only have “members” that correspond to the members of the interface?

<<2>> “can be defined...In addition...”  Are you trying to say an an object must support either exactly one or exactly two interfaces?  One provided by an interface definition and one provided by an implements statement? Or does this all mean something else entirely.

“ane” should be “an”

“Many object-oriented languages support interfaces, in which case the mapping of IDL interfaces to language interfaces is simple.”

This seems like an inappropriate thing to say in normative text.  If you really want to say it, make it a Note.  Whether or not the mapping with be simple depends upon the specifics of the target language semantics. I don’t see why this needs to be stated.

Partial Interfaces

It isn’t clear why the keyword “partial” is needed or what it’s exact usage rules are.  If partial interfaces are used does that mean that there is one Interface definition for a given identifier plus one or more PartialInterface definitions for the same identifier? What if there is more than one Interface?  May a PartialInterface precede the Interface?  It would seem that a human or machine could recognize and combine multiple Interface definitions using a common identifier without needing to see “partial”.  Is the motivation of “partial” to provide explicit notice that a definition is not the complete definition of a logical interface.  If that is the case, then it would seem to also be desirable to include “partial” on the  Interface definition to also give notice that it is incomplete.

The examples show two mutually referential interfaces.  What are the naming order and reference rules for module members? 3.3.1 says that constants must be uniquely named.  What about interfaces?

3.3.1 Constants

Why is the bnf production for the value of  constant definition name “ConstExpr” when it is not an expression?

“The value of an integer token is an integer, parsed in a manner common to many programming languages, as follows: ”  The red highlighted text adds no normative value.

“1 Let S be the string value of the integer token.”
Is “string value” well defined in this context?  should this say like “Let S be the sequence of characters matched by the integer token”.  Similarly for the float and string algorithms

algorithm step 4.  What if a character is out of bounds for the radix?  For example:  0778899

Please verify that for the string algorithm you really means UTF-16 and not UCS-2.  In other words, you intend that any Unicode supplemental characters actually are encoded using multiple 16-bit code units.

Are constants implicitly “static”?  They appear so, based upon the examples given in subsequent sections.  If this is the case don’t you need to explicitly specify this just like you specify what it means for an operation to be explicitly “static”.

3.3.2 Attributes
“An attribute is an interface member ... that is used to declare that objects implementing the interface will have an attribute with the given identifier whose value ” 
Perhaps the second “attribute” should be “member” in order to make this definition less circular.

Inherits Getter.  Isn’t the use of getters/setters to implement an attribute something that is determined by specific language bindings? In that case, why isn’t this expressed as an extended attribute?  Is the intent is simply to say that an inherited readonly attribute is generalized to be writable?  If so, why not simply provide for a “writable” or “not readonly” prefix rather than exposing the concept of getters for this purpose.

“If an implementation attempts to get or set the value of an attribute on an object implemented by user code...”  The purpose of this paragraph is not clear and whether what it is saying applies uniquely to attributes.  “objects implemented by user code” seems to be a key phrase. Is it simply trying to say that any exceptions generated by user code propagate back to user code?  Is this really a general WebIDL rule.  Wouldn’t this requirement be more appropriately stated in a language binding or perhaps in the section 7.1.3 of the HTML 5 specification HMTL 5 spec.  Note that a similar requirement is also  stated in 3.3.3.

3.3.3 Operations
What is the meaning if an identifier is used to name a regular operation in an inherited interface and that same identifier is also directly used as the name of a special operation?

“...if a value returned from invoking the operation cannot be converted to an IDL type...”  Should this really be “converted to the representation defined by the language binding that corresponds to the specified return-type” Callers
“Specifications SHOULD NOT use callers...”  This should probably be the first paragraph of this section.

3.3.6 Overloading

“In the ECMAScript language binding, constructors can be overloaded too.”  Why is ECMAScript specifically called out here?  Could this also be the case for other languages?  Perhaps it should say “Language bindings MAY support overloading of constructors”.

3.4 Dictionaries

Why is it necessary to specify that the the key value pairs defined to be ordered?  Particularly since ECMAScript does not define an enumeration ordering for  object properties .  Is there a important use case  that requires that order is specified? Or how, (from the perspective of WebIDL) is this ordering observable?

(The answers to some of my above questions are clearer after looking at 4.2.17. Perhaps a note here would eliminate such questions in readers of the spec.)

Dictionaries also should not be allowed as the return-type of an operation. (Note that they are already restricted from being the type of attributes).  The reason is to ensure that they are only used to specify values that pass into Web APIs and are not used to pass values back to user code.

3.8 Objects implemeting interfaces

“Language bindings define precisely how this check is made...”  Perhaps this should be “Language bindings or  the implementations of an IDL fragment define...”.  I can imagine  various different ways that an ECMAScript library implementing a Web API might recognize objects its specific objects that implement an interface.  It don’t think the ECMAScript binding specification should be  in the business of requiring such libraries to how to recognize their own objects.

3.9 Types

“...all conversions necessary will be performed before the operation is invoked...”  You don’t appear to actually define what it means to “invoke” an operation so it isn’t clear exactly what the “before” is referring to.  Does the above statement imply that type conversions must be performed by the caller’s invocation mechanism  rather than by a callee’s innovation prologue?  I don’t think it should.  A more reasonable interpretation would be that all conversions are performed before any of the specified functionality of the operation is carried out.  If this is the intent, then you should be more explicit about it.

3.9,13 DOMString

The first sentence says “ be interpretd as UTF-16 encoded strings...” but the next paragraph says “othing in this specificaiton requires a DOMString value to be a valid UTF-16 string”.  These two statements seem contradictory with each other.  Further more, you then go on to give what appeares to be a UTF-16 to UTF-32 conversion algorithm.  MUST a DOMString be a valid UTF-16 or is it just that a DOMString MAY contain such an encoding.  Pick one.  Also, why provide your own  UtF-16 to Unicode decoding algorithm.  Where does this algorithm come into play? Why not just reference the Unicode spec?

4.2.3 boolean
“IDL boolean values are represented by ECMAScript Boolean values”.  However, the algorithm given to convert an ECMAScript value to an IDL boolean applies the Ecma-262 ToBoolean abstract operation to the value as the first step of the conversions. ToBoolean accepts any ECMAScript value as an argument.  This seems to imply that IDL boolean values are representable by any ECMAScript value. 

The conversion from an IDL boolean to an ECMAScript value could be more clearly stated as:
The IDL boolean value token true is converted to the ECMAScript true value and the IDL boolean value token false is converted to the ECMAScript false value.

4.2.4, 4.2.5, 4.2.6, 4.2.7, 4.2.8, 4.2.9, 4.2.10, 4.2.11, 4.2.12, 4.2.13
See 4.2.3 comment, but regarding ToNumber instead of ToBoolean

4.2.4 byte

Algorithm step 3, “octet” should be byte.

4.2.10 and 4.2.11
Why aren’t these sections symmetric in their description of how to choose the best approximation for values > 253-1?

I think you need a note to explain why you canonicalize NaNs to 0x7fc00000

Why aren’t you cannonicalize NaNs when converting from IDL value to ECMAScript values?

Step 2: “float” should be “double”

need a note about canonicalizing NaNs

Steps 3-8 don’t do anything that wasn’t already done by ToNumber and ToNumber always yields and ECMASript numbers are defined to be IEEE doubles.  so all you really need is a step 3: Return x.

Why aren’t you cannonicalize NaNs when converting from IDL value to ECMAScript values?

4.2.14 DOMString
step 4: “same sequence of characters” should be “same sequence of code units”?

4.2.17 Dictionary types.

If bothers me that a complete copy of a dictionary must be made each time a dictionary is passed in and that the occurrences of the copy is observable by via ECMAScript accessor properties. Is this really necessary?  The main purpose of the copy seems to be to force a ECMAScript/IDL type conversion of each value in the dictionary.  Couldn’t these conversions be done on demand within the specification of operations that use dictionaries?  However wise you seem to make making any use of dictionaries unnecessarily expensive.

4.2.17 Sequence

I’m also trouble by the observable and mandatory copy both in and out for sequences.  For a large sequence where only a few elements need to be accessed the copying could could easily dominate the cost of the actual operation.

For an operation that returns a sequence, this spec. seems to require that the operation first internally construct the sequence and then make a copy of it. That seems unnecessarily.  Note that [[Put]] operators even on a new Array can be made observable via accessor properties that are inherited from Object.prototype.  To avoid this use [[DefineOwnProperty]] instead for storing into the new Array.  If the stores are not observable then you should have to mandate a copy out on return as long as the implementation of the operation doesn’t retain a reference to the resuylt object.

4.2.18 Arrays

“Note...most of the functions from the Array prototype object will not perform any useful operation on read only arrays” -- “most” is incorrect as the number of methods are are not sensitive to readonly-ness is larger than the number that are. Perhaps “some of” would be better wording.

I find the general concept of “platform array object” and the specific mapping into ECMAScript objects a bit rough.   The first paragraph says they are “similar” to native Array objects.  Can we enumerate all the ways they are different.  For example:
   they are never sparse
   their elements are always data properties
   an ECMAScrpt to WebIDL value conversion is always performed when store into an element
   Their [[Extensible]] property is always true.

(BTW, why the latter restriction on [[Extensible]]?  I understand why this might be desire for some usage of IDL Array but why all?  Couldn’t this condition be represented by an extended attribute?).  GetOwnProperty

Why is the [[Configurable]] attribute of length and array index properties reported as true when your[[DefineOwnProperty]] and [[Delete]] reject any attempt to set them to any other values or to delete them?  If you property reported configurable then you shouldn’t define to redefine [[Delete]] Platform array object [[DefineOwnProperty]]
Not precise enough, particularly with regard to deleting elements when the length changes  This can’t be less precise than ECMAScript [[Delete]]

You use “Reject” in this algorithm, but that is not a general ECMAScript algorithm operation.  It is only available for use in algorithms like because its meaning is explicitly defined in the prose that precedes the algorithm. 

4.2.21 Date

First algorithm, step 4: “the smae millisecond as V” should probably be “the same time value as D”.

4.3.1 [AllowAny]]
Editorial note: What if someone wanted to default all remaining types to a numeric type instead

Received on Tuesday, 23 August 2011 15:45:00 UTC