(In reply to comment #0)
> 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.

Re-worded this in the spirit for which the original sentence was intended. It should now be more readable and more technically correct.


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

Ha ha! Yeah, re-worked that sentence and linked to the propagation path info.


> type:
> 
> > The name must be a DOMString.
> 
> Redundant with the IDL.

Looks like this was fixed in some prior draft. At least I couldn't find that text.


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

Dropped the sentence. It was redundant.

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

Dropped it.


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

Agree. Dropped this sentence, leaving the explanitory sentence that follows.


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

Dropped the redundant sentence.


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

I removed this. I think it was supposed to be describing lambda (or anonymous) functions versus function pointers. It's irrelevant to the spec.


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

Updated.


> > 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 was fixed in a prior revision of the document, apparently.


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

I added the UA requirement text.


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

I fixed this in a previous update.


> > 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".
 
Also fixed in a previous update. Yes, the wording was a hurdle...


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

Now a "can" statement.


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

Got it now.


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

Added it. DOM L2 Range is OK for the purposes of these APIs.


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

I've previously deleted this entire section. In the conversion to WebIDL :)



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

Re-phrased this into a Note.

> > For backward compatibility reason, …
> 
> "reasons"

This was previously fixed :-)

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

This was re-written with the change to WebIDL exceptions previously.


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

This was redundant with the prior sentence under "Exceptions". So I removed it. (The exception was NotSupportedError.)

> 
> HTH
> Ms2ger

Yep. Thanks!