Re: [DOM3 Events] Some comments on Basic Event Interfaces

On 10/13/2011 03:19 AM, Jacob Rossi wrote:
> Ms2ger,
>
> Thanks for all your suggestions on DOM3Events.  There's some good grammatical fix ups that you suggest. These shouldn't affect implementers, but Doug and I can integrate these suggestions to improve the readability.

Please do. I would find it rather embarrassing if the Working Group 
published more documents with these errors.

> As for the functional comments:
>
>> 4.3 Interface EventTarget
>> =========================
>>
>>> The EventTarget interface must be implemented by all the objects
>>> which could be event targets in an implementation which supports an
>>> event flow.
>>
>> This is unimplementable without a normative description of "all the
>> objects which could be event targets in an implementation which supports
>> an event flow". I suggest leaving this up to the specifications that
>> define event targets, as happens in practice.
>
> I disagree. It's a statement that says if you have an interface that could have an event dispatched to it, then it must implement EventTarget. DOM Events is meant to be an event model which can be applied to lots of different objects and data structures.

I think that what you're really trying to say is more along the lines of
"Note: In an implementation which supports an event flow, all the 
objects which can be _event targets_ need to implement the |EventTarget| 
interface."

In particular, there is no reason for this paragraph to be a normative 
conformance requirement statement. Looking back at this section, I've 
found more problems. The next paragraph is:

> When used with the DOM event flow, this interface must be implemented
> by all proximal event targets and target ancestors, i.e., all DOM
> Nodes of the tree support this interface when the implementation
> conforms to DOM Level 3 Events and, therefore, this interface can be
> obtained by using binding-specific casting methods on an instance of
> the Node interface.

This starts off with a repetition of the previous one I complained 
about, AFAICT. Then it goes on to claim that a conforming implementation 
has Node objects implement the EventTarget interface, without a 
normative requirement to do that.

Looking for such a requirement, however, I noticed that "DOM event flow" 
is "defined" earlier to apply to Nodes in particular; without 
cross-referencing, this is easily mistaken for a general term. It should 
either be clarified or linked.

>>> Note: If the listener is a function, then it may be a reference to a
>>> function object or an inline function object literal.
>>
>> I'm not sure what this is supposed to mean.
>
> It just is a note towards authors that you can use inline functions as well:
> addEventListener("foo",function(evt) { //inline function}, false)

You shouldn't use MAY in that manner, then. Please change it to "can".

>>> This parameter may be optional, on an implementation-specific basis.
>>
>> This should be a "must" unless there is a very good reason against that.
>>
>
> The reason is that some languages do not support optional arguments.

In that case it should be a "must" for JavaScript implementations, at 
least. This behaviour is required for compatibility with the web as it 
exists today. However, to use this argument, it should not be optional 
on an *implementation*-specific basis, but on a *language*-specific basis.

>>> Note: For programming languages which do not allow optional method
>>> parameters, such as Java, the implementation may provide two
>>> EventTarget.addEventListener methods, one with 2 parameters, and one
>>> with 3 parameters.
>>
>> Is this a note or is it normative? You can't have both.
>
> This is a note that suggests a workaround for implementations in languages that don't support optional arguments. It's not normative. An implementation may do this, or it may not-up to the implementer (since optional useCapture isn't required).

If it isn't normative, it shouldn't use MAY. However, it should be a 
normative requirement for Java implementations.

>>> If a listener was registered twice, once for the capture and target
>>> phases and once for the target and bubbling phases, each must be
>>> removed separately.
>
>>
>> It's not clear if this is a UA requirement.
>
> This is intended for authors:
>
> target.addEventListener("foo",bar,false);
> target.addEventListener("foo",bar,true);
> target.removeEventListener("foo",bar,false);
>
> This only removes the first of the two listeners.

I don't see how your two statements are related. Indeed, only one is 
removed by the implementation. If you want to clarify this for authors, 
make it a note.

In fact, the UA requirement looks like a description of fact, and should 
instead read

 > Removal of an event listener registered for the capture and target
 > phases *must not* affect the same event listener registered for the
 > target and bubbling phases, and vice versa.

>>> The content authors should also remove their EventListener from its
>>> EventTarget after they have completed using the listener.
>>
>> I wonder why this is a "should".
>
> It's a coding "best practices" suggestion towards authors.

That reinforces my opinion that it should not be a "should". See RFC 2119.

>> EventException
>> --------------
>>
>> First, I think there is no need for a separate exception interface for
>> two single-use exception codes.
>
> We discussed this in Issue 179 and resolved that it is useful to have a separate exception to provide better context about the exception.

The Working Group has since decided that Web platform specifications 
should use DOMException, as explained in WebIDL: 
<http://dev.w3.org/2006/webapi/WebIDL/#idl-exceptions>. This resolution 
should be changed to reflect the consensus in the Working Group.

>> 4.5.1 Event creation
>> ====================
>>
>>> The Event objects created must be known by the DOM Events
>>> implementation; otherwise an event exception must be thrown.
>>
>> I'm not sure what this means. In any case, it should be specified which
>> exception is meant.
>
> document.createEvent("Foo") should throw if the implementation doesn't support the Foo event interface.  The spec does define which exception:
>
> "If the parameter does not match an event interface name supported by the implementation, the implementation must raise a NOT_SUPPORTED_ERRDOMException"

Then this sentence is both superfluous and unnecessarily confusing. In 
the first place, it uses the term "event exception", which could be 
construed as referring to the EventException interface (which needs to 
be removed).

Secondly, it duplicates the requirement you cite, and does so unclearly, 
as it talks about Event objects being created, not about the interface 
name that's passed to the createEvent method.

Thirdly, it is not actually at all clear that it refers to the 
createEvent method. It could be read as meaning that, say, dispatchEvent 
should throw when passed an Event that is not "known".

I recommend removing this sentence. In fact, it would be better if this 
entire section were removed: it doesn't clarify anything, but only 
serves to confuse readers. If you wish to stress that authors can create 
and dispatch synthetic events, a note in the DocumentEvent section could 
be useful.

> Regards,
> Jacob

Thank you for your response
Ms2ger

Received on Friday, 14 October 2011 21:01:43 UTC