Re: WebIDL editorial feedback

Cameron McCormack:
>> 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.

timeless:
> 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.

Will leave as is.

>>>> 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.

Did that.

>>>> 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].

OK, I will await that mail.

>>>> 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.

Not for security reasons; just for simplicity, again.

> 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].

If someone needs user object implementable exceptions, then we can allow 
it at that point.  For now, I don't see the need.

>> 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.

Perhaps.  You'll find this can/will phrasing a few times in the sections 
describing the extended attributes, since the actual requirements for 
handling them is in the language binding sections.  In a couple of those 
extended attribute sections I do link to which section handles them. 
I've added similar text now for most of the rest of them.

>> 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?

Good point, it didn't!  I reworked the wording and included some examples.

>> 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.

I think there are actually too many things to link to here (basically, 
every section that itself invokes the conversions in the type mapping 
section) to be useful.

>> 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 not; I updated the editorial note in the [Callback] section to 
mention the [UserObject] idea, and I edited an HTML comment towards the 
top of the file to remember about fixing up the consistency of linking 
to definitions.

>> 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

I still think it is unimportant at this point.

>> 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.

Oh, I see.  So I have been using the following convention:

   * If the variable's value does not change, I use "let x be ...".
   * If it does change, I declare it with "initialize x to be ...".
   * To change the value of an already declared variable, I say "set x
     to ...".

Maybe it's weird.

>> 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 :)

Noted that in the comment too.

>>>> 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].

OK.

>> 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`.

Oh, because you think of disqualified as being a state rather than an 
action there?  I think either way is OK.  I'm still going to leave it as 
is. :)

>>>> 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.

Isn't it sufficient that the text already says "the attribute will be 
reflected as an ECMAScript property in a way that means its behavior 
cannot be modified ... the property will be non-configurable"?  That 
seems to cover the __defineGetter__ case here.  I don't think that it's 
worth pointing out in particular.

>>> 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.

OK.  Well, I will still await requests for this for concrete APIs.

>> 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.

I'd need to link it somewhere then.  I don't link any other terms that 
you need to know from the ECMAScript spec.  There would be many of them...

Is it really confusing not to have that one linked?  I'm pretty sure 
that the only times "own" is used in the ES sense is in the phrases "own 
property", "own data property" and "own accessor property".

>> -- 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).

Still, I don't think "normal" Web IDL authors need to read the intricate 
sections of the spec that use the term.

>> 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.

I'm not sure how to get around that problem without requiring explicit 
annotations in the IDL for a particular Java class name.  Nobody will do 
that however.  I will ignore the potential problem.


 >> 3.3.4.3. Indexed properties
 >> Index getters and deleters MUST be declared to take a single
 >> unsigned long argument. Index setters and creators MUST be declared
 >> to take two arguments, where the first is an unsigned long.
 >
 > s/Index getters and deleters/Index property getters and deleters/
 > s/Index setters and creators/Index property setters and creators/

And s/Index/Indexed/.

Done, and for the "named" varieties in the following section too.

 >> There is no way to represent an constant array value in IDL.
 >
 > /an constant/a constant/

Done.


http://dev.w3.org/cvsweb/2006/webapi/WebIDL/Overview.html.diff?r1=1.352;r2=1.353;f=h

If the resolutions to these comments is acceptable, could you please 
indicate so.

Thanks,

Cameron

Received on Wednesday, 24 August 2011 04:34:35 UTC