[DOM3 Events] Some comments on Basic Event Interfaces

Hi Doug, Jacob

Reading through the D3E section on Basic Event Interfaces, I found a 
number of things that could benefit from clarification.

4.1 Interface Event
===================

> An object which implements the Event interface must be passed as the
> parameter to an EventListener.

Interfaces don't have parameters, and this seems like a strange place to 
put this requirement.

eventPhase:

> Used to indicate which phase of event flow is currently being
> accomplished.

There must be a better word than "accomplished" that could be used here.

type:

> The name must be a DOMString.

Redundant with the IDL.

initEvent:

> This method sets the Event.type attribute to eventTypeArg.

Either this is redundant with the "Parameters" section below, or the 
respective requirements for bubbles and cancelable are missing.

4.2 Interface CustomEvent
=========================

initCustomEvent:

> detailArg of type any
>     Specifies CustomEvent.detail. This value may be null.

This last sentence is redundant with the type of the argument.

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.

addEventListener:

> If listener is a function that also has a handleEvent method, the
> function itself must be used as the callback and not its handleEvent
> method.

This is redundant with the previous sentence, so should be a note and 
should not use "must".

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

About useCapture:

> This parameter may be optional, on an implementation-specific basis.

This should be a "must" unless there is a very good reason against that.

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

removeEventListener:

Same comments, and

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

4.4 Interface EventListener
===========================

EventListener
-------------

> The EventListener interface is the primary way to handle events.
> Content authors must define on object, such as a function, which the
> EventListener interface and register their event listener on an
> EventTarget.

I don't believe this is correct English.

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

> Copying a Node, with methods such as Node.cloneNode or
> Range.cloneContents, must not copy the event listeners attached to
> it. Event listeners must be attached to the newly created Node
> afterwards, if so desired.

And why this is a "must".

> Moving a Node, with methods Document.adoptNode, Node.appendChild, or
> Range.extractContents, must not affect the event listeners attached
> to it.

You seem to have missed "such as" here.

It also seems like a reference to a DOM Range specification is missing.

EventException
--------------

First, I think there is no need for a separate exception interface for
two single-use exception codes.

Second,

> Event operations may throw an EventException as specified in their
> method descriptions.

uses "may" inappropriately.

Third, the "code" attribute is not actually defined in the prose.

Fourth, it makes little sense to put this in §4.4 "Interface
EventListener". I would suggest a separate section.

4.5 Interface DocumentEvent
===========================

The description of createEvent's eventInterface argument has:

> If the Event is to be dispatched via the EventTarget.dispatchEvent()
> method, the appropriate event initialization method must be called
> after creation in order to initialize the Event's values.

This suggests that the user agent must call initEvent, which I assume 
isn't the goal here.

> For backward compatibility reason, …

"reasons"

> If the parameter does not match an event interface name supported by
> the implementation, the implementation must raise a NOT_SUPPORTED_ERR
> DOMException

Missing period at the end of the sentence, and redundant with the 
"Exceptions" section below.

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.

HTH
Ms2ger

Received on Thursday, 18 August 2011 17:11:24 UTC