W3C home > Mailing lists > Public > public-script-coord@w3.org > July to September 2011

Re: WebIDL editorial feedback

From: timeless <timeless@gmail.com>
Date: Mon, 22 Aug 2011 18:33:08 -0400
Message-ID: <CAACrNNcb8JaPozg9Dij3c3S3Cg1=-c-_EGZudtdWzChRh71zKw@mail.gmail.com>
To: Cameron McCormack <cam@mcc.id.au>
Cc: public-script-coord@w3.org
I've left some placeholders [x1]..[x6], sorry

> Something went wrong editing that sentence.  I've replaced it with:

ok

> I added a note after the IDL block:

ok

> This is about using
>   two consecutive U+003A COLON (":") characters
> and
>   the string “::”
> to mean the same thing?

yes

> Yeah, that's a good point.  I introduced a term
> "double colon" to refer to this.

sounds good

> Yeah.  Fixed that, and a small problem in the final bullet of that list.

sounds good

> So my rules there are:
>   * If the container has only single line declarations inside it,
>     don't put any blank lines inside the container.
>   * Otherwise, if it has any declarations that take more than one
>     line, put a blank line before each one.

> I tried both adding and removing blank lines, but I wasn't happy with
> either, so I left it as is.

I think what I'd probably want is:
    * If a blank line was added at the beginning of a block, include a
matching blank line at the end of the block for symmetry.

but bike-shedding over style isn't a good idea, so that's just a
suggestion, no obligation.

>>> An interface is a definition (matching Interface) that defines an
>>> interface that objects in the system can implement.
>> "the system" seems odd.
> Would s/the system/a conforming implementation/ work?

i think it would help.

i think the other problem you have is passive voice, the `objects` are
just floating around, it's unclear (intentionally, and grammatically)
who created them.

> I did "Dog?" and "Human?".

ok

> No, I'll move it down to GetRaises for symmetry.

ok

> I think it would need to be more complicated than that because you need
> a comma before the variadic argument if it is not the only argument, or
> to omit it if it is.  I'm going to leave the grammar a bit lax here and
> rely on the prose to disallow "..." in the middle of an argument list to
> avoid complicating it.

ok

> No it doesn't.  Since it allows the special keywords in any order, you'd
> get an explosion of productions in the grammar if it were to.

ok

> Not going with the grammar suggestion above, so I will leave this.

ok

> I think "implementation of the IDL" is consistent with the wording I use
> in the conformance classes defined at the top of the document, so I will
> leave this one.

ok

> I'm going to rename them to "named property getter" and "indexed
> property getter".  It's a bit more verbose, but it's a more accurate
> description.

sounds good

> Instead I did
>   If an interface supports named properties, then the interface
>   definition MUST be accompanied by a description of the ordered set of
>   names that can be used to index the object at any given time.

ok

> Used "named property getters" per above.

ok

> I added this paragraph to the #idl-special-operations section:
>   Some language bindings, such as ECMAScript, do not distinguish
>   assignment to an existing indexed or named property and the creation
>   of a new one. Regardless, it is the creator that is invoked when an
>   attempt is made to create a new indexed or named property, and the
>   setter when the property already exists.

ok

> It's language binding specific.  I will point that out with this
> sentence:
>   It is language binding specific whether it is possible to invoke
>   a static operation through a reference to an instance of the
>   interface.

ok

> Added a paragraph similar to the one in the interfaces section.

ok

> It's consistent with the productions for attributes, constants, etc.

ok

> I want to allow it so that people can use their own extended attributes
> there if they want.

should there be a note in the spec explaining this intent?

> Fixed as above.

ok (sigh, that text is a sign of copy paste where i mistyped the key word)

> I had a rule I was (mostly) following, which was to link it the first
> time it appears in a sequence of consecutive paragraphs.  Any other
> block such as an <ol>, a note, and IDL block etc. would reset that.

sounds complicated :)

> I probably didn't apply the rule consistently enough.  I'll think about
> linking each instance of the word, but I won't do that right now.

sounds good, and yeah, having that change mixed in with the changes
for the rest of my comments would make reviewing the changeset
painful.

> That text sounds good.  I added it with slight tweaks, and removed the
> example of using instanceof in the code block.

cool, i guess that earns me a reference in credits :)

>>> The type being given a new name is specified after the typedef
>>> keyword (matching Type), and the identifier token following the type
>>> gives the name. The Type MUST NOT be a scoped name that resolves to
>>> an interface.

>> I think one of 'Type' or "NOT" here is wrong, I was reading:
>>
>>> [16]  Typedef → "typedef" Type identifier ";"
>>
>> And assumed the 'NOT' was applying to 'Type', the prose probably
>> wants: s/Type/type/ -- to mean 'The type [being given the new name
>> `identifier`] MUST NOT ...', or s/Type/identifier/.

> No, I think it's correct as is.

I'm going to try again.

Basically, I agree with your goals (the following bits), but I'm
having a really hard time reading your prose and not getting entirely
confused by `type`, `typedef`, `Type`, `identifier`, etc.

Actually. I think I'll probably send this as a distinct email [X1].

> I wanted to prevent typedefs from being used to give new names
> to existing interfaces, just for simplicity.

sounds reasonable

> I should extend that to dictionaries, too.

sounds reasonalbe

>>> 3.8. Objects implementing interfaces
>>> There is no way for a user object to represent an exception.
>> ?
> I want to state that in systems implementing some IDL, you can't use
> user code to implement the exception "class".  I'm open to suggested
> wording there.

ok. i presume you're trying to do this for security reasons or something.

One of the things I did a long time ago was implement code which
implemented objects which implemented [xpcom] interfaces. And it was
perfectly natural and rather useful to be able to provide my own
exception objects. Typically the exceptions one can create from host
systems (new FooException) more or less universally suck.

perhaps this should be discussed in its own thread [X2].

> OTOH, you're not allowed to use an exception as a type for attributes,
> operation arguments, etc. anyway, so it probably doesn't matter.

i.e. perhaps this is out of scope?

> Makes sense.

:)

> This section is only intended to restrict what kinds of interfaces user
> objects can implement, not any other kinds of constructs like
> dictionaries.  There's also no distinction between user objects and
> platform objects for dictionaries.

ok

> At the IDL level, dictionaries aren't even objects -- they're just
> an abstract data type.  I think it's fine not to mention them here.

ok

> I use wording like "can" and "cannot" when it is just describing the
> consequences of other RFC2119 requirements in the document.

ok, i wonder if you should have links (sorry, i generally review
text/plain versions of documents) to the relevant sections which cause
such constraints.

>> Afaict, this isn't forbidden or at least actively discouraged:
>>
>> interface Foo {};
>> Foo implements Bar;
>> Foo implements Baz;
>> interface Bar { attribute short x; attribute short y; };
>> interface Baz { attribute short x; attribute short z; };
>>
>> There is text in a couple of other sections which talks about things
>> being undefined or needing to be clarified by prose, but there
>> definitely isn't any near the <implements> section.

> Yeah, fair enough.  I should just disallow this.

good

> I've added the following to the #idl-implements-statements section:

>   Implements statements MUST NOT be used such that the identifier of any
>   member of one interface’s consequential interfaces is the same as
>   the identifier of one of the interface’s own members.

that covers:

 interface Foo { attribute short x; attribute short y; };
 Foo implements Baz;
 interface Baz { attribute short x; attribute short z; };

Does "one of the interface's own members" actually cover my initial case?

> and removed the talk of this case being undefined in
> #es-implements-staements.

good

> Not using RFC2119 terminology here because this is just a general
> statement of what the language bindings require.

ok

> Again, this is a consequence of MUSTs in the later sections describing
> the properties that exist for attributes and operations.

see earlier question about references which cause constraints, i think
they might be helpful.

> It's valid English, but I'll put the "is" in there explicitly for
> symmetry with the following sentence.

:)

> I don't think MAY is right, here.

ok

> This is also informative text that describes normative requirements
> later on.

see earlier.

> It exists because I want to disallow `Type??` but allow `Type?[]?[]?`
> etc. and also yes to disallow `any?` but allow `any[]`.

ok

> I will use "needs to be used".

ok

> Moved it to the front of the sentence.

ok

> That sounds slightly better.

good

> I will consider that.  I haven't made the change right now though.

is there a place i can see a list of considers?
/will you let me know when you decide, or do i need to wait for the
last Last Call to find out?

> There is an example in the #es-Callback section.  I will reword the
> sentence that links to it to state that it's got an example there too.

ok

> I'll do s/any/any ECMAScript execution context associated with the
> environment/ and s/global environment is created/environment is
> created/.

i'll need to review the diff to parse this one (probably ok)
-- yes, i know you sent the diff, i intended to review it anyway

> Yeah, I think that's a good change.

good

> It is the following list.  I tried to make this clearer by saying in
> #idl-any that any values remember what paricular IDL type they are, and
> then here in this section I now say:

>   Otherwise, the rules for converting the _particular type_ of the IDL
>   any value as described in the remainder of this section are performed.

ok

> Actually, I will make this say
>   ECMAScript functions on user objects that implement an operation whose
>   IDL specifies a void return type MAY return any value, which will be
>   discarded.

sounds better

> I still use "will" because the actual requirement for discarding it is
> done in the section later that talks about invoking operations on user
> objects implemented in JS.

ok

> Good point, although the algorithm does ensure that the number is
> positive first.  At the top of #ecmascript-binding it does say that the
> conventions of ES-262 section 5.2 are used, and that section defines
> modulo.  I'll point out more explicitly that the mathematical operations
> from that section are used here.

good

> I don't think this is detectable.  I also don't think it matters if the
> length increases with each [[Put]], so I'm going to leave this one.

ok

> Went with the latter.

ok

>>> // "hi" will be alerted before drawPolygon() returns.
>> technically it will be alerted before drawPolygon() is called, right?
> Both are true. :-)

it might be helpful to use the stronger statement :)

> Sure.  (My personal style is usually to omit semicolons in case of a
> single return statement.)

thanks

> I don't quite follow your example.

there was at least one typo in it (change/changed), sorry.

> I changed the existing example a bit, maybe you can take a look.

i will

> I think it wasn't.  I've pointed out now that platform array objects are
> platform objects, and thus are associated with a particular global
> environment.

good

> I kind of liked how it sounded like the objects were resisting. :)

:)

> I did s/defy being/cannot be/.

good

> Don't think that's necessary.

ok

> I think it'll be indistinguishable whether the function itself or one it
> delegates to throws the TypeError.  It's probably not worth worrying
> about.

debugging mechanisms might make it distinguishable, and there seems to
be some work to try to expose more of this. dunno

> Do you mean the choice of the variable name /E/ or the convention of
> writing E_0..n?

the former, as well as suddenly conjuring an actual variable without a
step to conjure it.

> I think I'll rename it to /values/, anyway.

sounds good

> I should have stronger conventions around variable name choices and
> capitalisation,

yes

> but I haven't got around to sorting that out.

lemme know when you do, i'll review again :)

> Yeah.

good

>>> var a = [4, 8, 15, 16, 23, 42];      // Numbers can be assigned into
the array.

s/can/[that] will/ -- sorry, i can send this as a new email if you prefer [X3].

 >> for (var i = 0; i < 6; i++) {
 >>  results.numbers[i] = a[i];
 >> }
 >> results.numbers = a;                 // This has no effect, since
numbers is
 >>                                      // read only.
 > This should be done before the for loop above, otherwise it's
 > impossible to determine that it has no effect.

I think it's fine -- the effect I'm more interested in demonstrating is
that changing a afterwards does not affect the IDL array.

> I've added that at the end of the example.

ok

>> A `results.numbers != a` statement might be useful if that's the case.
> OK.

good

>>> Platform objects returning an ECMAScript Date object from attributes,
>>> operations or exception field do not hold on to a reference to the
>>> Date object.
>> s/on to/onto/
> I think it's fine as is.

peanut gallery? [X4].

> I think of script as a mass noun too, but OK.

thanks

>>> When the [AllowAny] extended attribute is present on the argument,
>>> that disqualification is not performed.
>> s/performed/applied/ ?
> I think "performed" is fine.

i'm trying to remember why i didn't suggest `active`, i don't think
one would typically `not perform a disqualification`.

> I did mean "on".

:)

> Yes, that's better.

:)

> There is one in the #ReplaceableNamedProperties section.

ok

> So I replaced that paragraph with:
>   If the [Replaceable] extended attribute appears on a read only
>   attribute, it indicates that setting the corresponding property on the
>   platform object will result in an own property with the same name
>   being created on the object which has the value being assigned.  This
>   property will shadow the accessor property corresponding to the
>   attribute, which exists on the interface prototype object.

ok

> I reworded the example in line with the above change, too.

ok

> Added.

ok

> I added a note explicitly stating that [TreatNullAs] on a "DOMString?"
> type is disallowed.

ok

> Yes, did so.

ok

> No, since [TreatNullAs] cannot be put in a "DOMString?" type.

ok

> Fixed.

good

>>> 4.3.15. [Unforgeable]
>>> If the [Unforgeable] extended attribute appears on a read only
>>> attribute,
>>> it indicates that the attribute will be reflected as an ECMAScript
>>> property
>>> in a way that means its behavior cannot be modified and that
>>> performing a
>>> property lookup on the object will always result in the attribute’s
>>> property
>>> value being returned.
>>
>> This doesn't say that a forging getter isn't fired first before
>> returning the unforged value.
>
> I'm not sure what you mean.

### /* idl */
interface Unforgable {
  [Unforgable] attribute DOMString signer;
}

interface Yapper {
  attribute Unforgable papers;
}

/* the standard papers signer for Window should return "I'm a signed window" */
Window implements Yapper;
###

### /* js */
yapper = papers;
yapper.__defineGetter__("signer", function forger(){alert("I'm
running"); return "I'm discarded"; });
alert(yapper.signer);
###

The end says `the object will always result in the attribute's
property value being returned`, but that doesn't seem to preclude
triggering a forged getter and discarding its return value before
returning the correct value.

> I've not tended to include examples of invalid IDL, but anyway I don't
> think it's necessary here for understanding.

ok

> Here would be OK, though, since it's a bit more complicated.

> Actually I am going to further restrict where [Unforgeable] is allowed;
> please take a look at the updated text.

will do

> It's simpler now.

oh good :)

> I removed the consequential interface part of the restriction because of
> the changes mentioned earlier in this email about disallowing mixing in
> interfaces if they have members with clashing names.

ok

> I linked to the definition of "conforming ECMAScript implementation" to
> make that clearer.

ok

>>> 4.5. Interfaces
...
>> s/(The characteristics .*) is (.*)/$1 are $2/g;
> OK.

i'll need to review the diff :)

>> --in case i forget to tag some other instances...
> (There was only one more instance.)

:)

> Indeed.  The earlier sentence has been removed, and this one here is
> correct.

good

> Meh. :)

:)

>> interface A {}
>> interface B : A {}
>> interface C {
>>   void d(A[] a);
>>   attribute B[] e;
>> }
>>
>> c = new C;
>> c.d(c.e);
>>
>> I don't think that this is handled properly (compare with the next
>> case which tries to handle inheritance).
> I see.  I'm not sure it's worth handling this at this point -- if people
> can point out cases where this would be useful, I'll allow it.

In XPCOM land, the easiest place for something like this to happen is for:

interface ReadableFoo {};
interface WritableFoo : ReadableFoo {};

interface HouseOfFoos {
  attribute WritableFoo[] foos;
};
interface SummarizeListOfFoos {
  any summarize (ReadableFoo[] foos);
};

I think some of the interfaces being discussed currently do map to
Readable/Writable splits. I'm not sure how often people actually
define array lists, but it definitely can happen.

> Ah, it should be s/inherit from/are an inherited interface of/.

yes

> I don't want the overload resolution algorithm to have to inspect all
> the types of the array elements.  So any array type should match.

ok

> I see I missed out sequence types here, so I'll add them too.

cool

> I want not to disallow:

ok

> OK.

:)

> Indeed it should be candidates, as Lachy points out too:
> http://www.w3.org/mid/4E2580C8.6050106@lachy.id.au

yeah, I think i saw that fly by and smiled

> I'm not sure I like the "arbitrarily" in here anyway.

as well you shouldn't ;-)

> Probably I should just require that specifications do have rules that
> correctly resolves the ambiguity, but I don't have a conformance class
> for specifications at the moment. :(

smells like work

> n is already used earlier in the algorithm (well, as input to it).  It
> shouldn't have the same count, because of cases like

ok

> It should be guaranteed that m ≤ n here.

ok

> Then it returns it.  I don't think there is a need to constrain this,
> since returning a bad value is already bug.

ok

>>> 4.5.4. Constants
>>> For each constant defined on an interface A, there MUST be a
>>> corresponding property on the interface object, if it exists,
>>
>> I expected any text relating to <interface-prototype-object> getting
>> a constant to be here, not later. You can add the special stuff later
>> and still have the general bit for <interface-prototype-object> here
>
> Do you mean you'd rather the order be swapped around to describe them
> being on the interface prototype object first, and then on the interface
> object?  I used the current order because it's more normal to use
> Node.ELEMENT_NODE rather than myNode.ELEMENT_NODE.

[X5]


> Thinking about it now, it probably shouldn't.

:)

> No...

:)

> OK.  I was going with the official Unicode name of the character,
> though.

yeah, which i never searched on because i didn't think to look for it
:(, and my browser's find() function isn't smart enough to use a
thesaurus while searcing [XXX this is a bug, someone please fix it for
me].

> Sure.

> So I've just simplified things even further: I've added a sentence to
> #idl-names disallowing any construct from having the identifier
> "prototype", "constructor" or "toString".

good

>>> 4.5.6. Operations

> The above check is just meant to prevent you from doing:
>   var o = { };
>   MyInterface.prototype.f.call(o);

understood

> Web IDL doesn't really talk about wrapping user objects as platform
> objects.  If specifications wanted to require this, they could say this
> in prose.  But I don't think we want it universally, do we?

dunno [X6]

> Per above comments, that sentence has disappeared from
> #es-implements-staements.

ok

> Sometimes I like eliminating sentence-ending prepositions, but I think
> in this case it makes the sentence a little less clear.

alright

> It's "own property" in the ECMAScript sense.

right, i understand that it's an ecmascript sense.

> Not sure if it's necessary to define this term

i'm not necessarily asking you to define it, merely identify each case
where `own` is really the ecmascript sense and not the standard
English word.

> -- it should be known if you are familiar with
> ECMAScript, which you'll need to be if implementing.

but some WebIDL authors will not be implementors (I speak from working
with Working Groups which seem much more interested in writing
specifications and asking others to implement them than in being
implementers themselves).

> I think I'll just update Web IDL in that case.

ok

> Addressed per above comments.

ok

> Earlier I describe objects as being "associated with" global
> environments, so I think this wording here is OK.

ok

> OK, I changed one earlier example where code to use a try block, where
> otherwise the remaining code in the example wouldn't be run.

good

> It is, but only because in 5.2.20 there are a few standardly named
> methods that need to be defined on there.  I think if I showed an
> outline of the Java interface definition for this section, it wouldn't
> be that useful.

ok

> Fair point.

:)

> Some of my example IDL fragments define interfaces named
> FooUtils, too.  I added a sentence saying that the Java class is named
> _FooUtils in this case.

probably ok. i'm slightly worried about the case where e.g.
WindowUtils comes later and someone has already compiled their Java
assuming it doesn't exist.

>> Will this mapping fall appart horribly? :)
> Yes. :-)
> I will define it so that the above will get names getI() for the first
> one and _getI() for the second.

ok

> I will also forbid defining interface members with identifiers that
> begin with an underscore entirely, for simplicity.

ok

> I added some text and an example to that section to clarify inheriting
> the implementation of an interface.

ok
Received on Monday, 22 August 2011 22:33:37 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 8 May 2013 19:30:04 UTC