[Bug 16339] New: Some comments on Basic Event Interfaces

https://www.w3.org/Bugs/Public/show_bug.cgi?id=16339

           Summary: Some comments on Basic Event Interfaces
           Product: WebAppsWG
           Version: unspecified
          Platform: PC
               URL: http://lists.w3.org/Archives/Public/www-dom/2011JulSep
                    /0131.html
        OS/Version: Windows NT
            Status: NEW
          Keywords: LC
          Severity: normal
          Priority: P2
         Component: DOM3 Events
        AssignedTo: travil@microsoft.com
        ReportedBy: travil@microsoft.com
         QAContact: public-webapps-bugzilla@w3.org
                CC: mike@w3.org, annevk@opera.com, Ms2ger@gmail.com,
                    www-dom@w3.org


This is a PORT of TRACKER, ISSUE-186 (DOM3Events Outstanding Issues)
https://www.w3.org/2008/webapps/track/issues/186
[see http://lists.w3.org/Archives/Public/www-dom/2011JulSep/0131.html]

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

-- 
Configure bugmail: https://www.w3.org/Bugs/Public/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
You are on the CC list for the bug.

Received on Monday, 12 March 2012 21:50:24 UTC