Re: Event handlers in RTCPeerConnection

On 2012-10-01 19:43, Martin Thomson wrote:
> On 1 October 2012 07:42, Adam Bergkvist <adam.bergkvist@ericsson.com> wrote:
>
>> If you think that it's insufficient, please give an example on how you think
>> it can be clarified.
>
> Quoting the editors draft (which I assume is very recent):
>    onicecandidate of type EventHandler
>      This event handler, of event handler event type onicecandidate ,
> must be supported by all objects implementing the RTCPeerConnection
> interface. It is called any time there is a new ICE candidate added to
> a previous offer or answer.
>
> There is no link to the type of event, and the link to Section 15 is
> hidden under the text "onicecandidate", which is exactly the link that
> I followed.  Given that I followed a link labelled "onicecandidate", I
> didn't expect this to go anywhere new.  Maybe something as simple as
> removing the "on" would be sufficient.  I notice that other events
> don't have "on".

Yes. The "on" shouldn't be a part of the event type. It's only the event 
handler attribute that should be named "on" + <event type>. I'll go 
ahead and fix that.

> I'm surprised that this event isn't described in Section 15.  It's
> probably the only event that hasn't undergone significant changes.

There's a description in the onicecandidate attribute description we 
could pretty much reuse.

Just a side note: I see that several event handler attributes have a 
short description like: "It is called when..". That text should move to 
the table in section 15. I don't think it's correct to have text of that 
kind there because the event handler is only triggered as a result of 
the event being fired. The reason for firing the event must be 
documented elsewhere anyhow.

> Why is Section 15 non-normative?

Good question. My guess is that it's a summary that doesn't provide any 
implementation requirements or new information that's not found 
elsewhere in the document. I've seen similar sections in other 
specifications (can't remember which ones right now).

At some point we've talked about removing it, but perhaps it serves a 
purpose since all the event types are linked there and simple events 
(that use the Event interface) aren't mentioned in section 14.

/Adam

Received on Tuesday, 2 October 2012 08:56:54 UTC