Add a section summarizing different ICE candidate events.

Fixes #1213.

We've ended up with three different types of events that all use the
same "icecandidate" event, and are fired in different places. Which is,
understandably, confusing to most readers of the specification.

This PR adds a note to the RTCPeerConnectionIceEvent section summarizing
the different types of events, describing when they're fired, how
they're represented in the RTCPeerConnectionIceEvent, and what the
application should do with them.

webrtc.html

@@ -3930,6 +3930,43 @@ <h4><dfn>RTCPeerConnectionIceEvent</dfn></h4>
         type <code>relay</code>, the <code>url</code> property of the event
         MUST be set to the URL of the ICE server from which the candidate was
         obtained.</p>
+
+        <div class="note">
+          The <code><a>icecandidate</a></code> event is used for three
+          different types of indications:
+          <ul>
+            <li>
+              <p>An candidate has been gathered. The <code><a
+              data-link-for="RTCPeerConnectionIceEvent">candidate</a></code>
+              member of the event will be populated normally. It should be
+              signaled to the remote peer and passed into
+              <code><a data-link-for="RTCPeerConnection">addIceCandidate</a></code>.</p>
+            </li>
+            <li>
+              <p>An <code><a>RTCIceTransport</a></code> has finished gathering a
+              <a>generation</a> of candidates, and is providing an end-of-candidates
+              indication as defined by Section 8.2 of [[TRICKLE-ICE]]. This is
+              indicated by <code><a data-link-for="RTCPeerConnectionIceEvent">candidate</a>.<a
+              data-link-for="RTCIceCandidate">candidate</a></code> being set to an
+              empty string. The <code><a
+              data-link-for="RTCPeerConnectionIceEvent">candidate</a></code> object
+              should be signaled to the remote peer and passed into
+              <code><a data-link-for="RTCPeerConnection">addIceCandidate</a></code>
+              like a typical ICE candidate, in order to provide the
+              end-of-candidates indication to the remote peer.</p>
+            </li>
+            <li>
+              <p>All <code><a>RTCIceTransport</a></code>s have finished
+              gathering candidates, and the <code><a>RTCPeerConnection</a></code>'s
+              <code><a>RTCIceConnectionState</a></code> has transitioned to
+              <code>"<a data-link-for="RTCIceConnectionState">completed</a>"</code>.
+              This is indicated by the
+              <code><a data-link-for="RTCPeerConnectionIceEvent">candidate</a></code>
+              member of the event being set to <code>null</code>. This only exists
+              for backwards compatibility, and this event does not need to be
+              signaled to the remote peer.</p>
+            </li>
+        </div>
         <div>
           <pre class="idl">
           [ Constructor (DOMString type, optional RTCPeerConnectionIceEventInit eventInitDict)]