Add an introductory API overview block for EventSource

This change adds a domintro block in the section that defines the EventSource
interface. It also adds markup to cause more implementor-specific parts of the
“Server-sent events” section to be suppressed in the developer edition.

Author: sideshowbarker

source

@@ -93595,6 +93595,8 @@ dictionary <dfn>EventSourceInit</dfn> {
   boolean <dfn data-x="dom-EventSourceInit-withCredentials">withCredentials</dfn> = false;
 };</pre>
 
+  <div w-nodev>
+
   <p>Each <code>EventSource</code> object has the following associated with it:</p>
 
   <ul>
@@ -93615,6 +93617,58 @@ dictionary <dfn>EventSourceInit</dfn> {
   <p>Apart from <span data-x="concept-EventSource-url">url</span> these are not currently exposed on
   the <code>EventSource</code> object.</p>
 
+  </div>
+
+  <dl class="domintro">
+
+   <dt><var>source</var> = new <code subdfn data-x="dom-EventSource">EventSource</code>(
+   <var>url</var> [, { <code data-x="dom-EventSourceInit-withCredentials">withCredentials</code>:
+   true } ])</dt>
+   <dd>
+    <p>Creates a new <code>EventSource</code> object.</p>
+
+    <p><var>url</var> is a string giving the <span>URL</span> that will provide the event
+    stream.</p>
+
+    <p>Setting <code data-x="dom-EventSourceInit-withCredentials">withCredentials</code> to true
+    will set the <span data-x="concept-request-credentials-mode">credentials mode</span>
+    for connection requests to <var>url</var> to "<code data-x="">include</code>".</p>
+   </dd>
+
+   <dt><var>socket</var> . <code subdfn data-x="dom-EventSource-close">close</code>()</dt>
+
+   <dd>
+    <p>Aborts any instances of the <span data-x="concept-fetch">fetch</span> algorithm started for
+    this <code>EventSource</code> object, and sets the <code
+    data-x="dom-EventSource-readyState">readyState</code> attribute to <code
+    data-x="dom-EventSource-CLOSED">CLOSED</code>.</p>
+   </dd>
+
+   <dt><var>source</var> . <code subdfn data-x="dom-EventSource-url">url</code></dt>
+
+   <dd>
+    <p>Returns the <span data-x="concept-EventSource-url">URL providing the event stream</span>.
+   </dd>
+
+   <dt><var>source</var> . <code subdfn data-x="dom-EventSource-withCredentials">withCredentials</code></dt>
+
+   <dd>
+    <p>Returns true if the <span data-x="concept-request-credentials-mode">credentials mode</span>
+    for connection requests to the <span data-x="concept-EventSource-url">URL providing the
+    event stream</span> is set to "<code data-x="">include</code>", and false otherwise.</p>
+   </dd>
+
+   <dt><var>socket</var> . <code subdfn data-x="dom-EventSource-readyState">readyState</code></dt>
+
+   <dd>
+    <p>Returns the state of this <code>EventSource</code> object's connection. It can have the
+    values described below.</p>
+   </dd>
+
+  </dl>
+
+  <div w-nodev>
+
   <p>The <dfn><code data-x="dom-EventSource">EventSource(<var>url</var>,
   <var>eventSourceInitDict</var>)</code></dfn> constructor, when invoked, must run these steps:</p>
 
@@ -93679,6 +93733,8 @@ dictionary <dfn>EventSourceInit</dfn> {
   <p>The <dfn><code data-x="dom-EventSource-readyState">readyState</code></dfn> attribute represents
   the state of the connection. It can have the following values:</p>
 
+  </div>
+
   <dl>
 
    <dt><dfn><code data-x="dom-EventSource-CONNECTING">CONNECTING</code></dfn> (numeric value 0)</dt>
@@ -93697,6 +93753,8 @@ dictionary <dfn>EventSourceInit</dfn> {
 
   </dl>
 
+  <div w-nodev>
+
   <p>When the object is created its <code data-x="dom-EventSource-readyState">readyState</code> must
   be set to <code data-x="dom-EventSource-CONNECTING">CONNECTING</code> (0). The rules given below
   for handling the connection define when the value changes.</p>
@@ -93708,6 +93766,8 @@ dictionary <dfn>EventSourceInit</dfn> {
   data-x="dom-EventSource-CLOSED">CLOSED</code>.</p> <!-- this also causes all the message events to
   stop firing, even if they were queued before close() was called -->
 
+  </div>
+
   <p>The following are the <span>event handlers</span> (and their corresponding <span data-x="event
   handler event type">event handler event types</span>) <span w-nodev>that must be</span> supported,
   as <span>event handler IDL attributes</span>, by all objects implementing the
@@ -93724,6 +93784,7 @@ dictionary <dfn>EventSourceInit</dfn> {
 
   <hr>
 
+  <div w-nodev>
 
   <h4 id="sse-processing-model"><span id="processing-model-9"></span>Processing model</h4>
 
@@ -93863,8 +93924,12 @@ dictionary <dfn>EventSourceInit</dfn> {
   data-x="queue a task">queued</span> by <code>EventSource</code> objects is the <dfn>remote event
   task source</dfn>.</p>
 
+  </div>
+
+
+  <h4 w-nodev>Parsing an event stream</h4>
 
-  <h4>Parsing an event stream</h4>
+  <h4 w-nohtml>The event stream format</h4>
 
   <p>This event stream format's <span>MIME type</span> is <code>text/event-stream</code>.</p>
 
@@ -93894,13 +93959,15 @@ any-char      = %x0000-0009 / %x000B-000C / %x000E-10FFFF
   pair, a single U+000A LINE FEED (LF) character, or a single U+000D CARRIAGE RETURN (CR)
   character.</p>
 
-  <p>Since connections established to remote servers for such resources are expected to be
+  <p w-nodev>Since connections established to remote servers for such resources are expected to be
   long-lived, UAs should ensure that appropriate buffering is used. In particular, while line
   buffering with lines are defined to end with a single U+000A LINE FEED (LF) character is safe,
   block buffering or line buffering with different expected line endings can cause delays in event
   dispatch.</p>
 
 
+  <div w-nodev>
+
   <h4 id="event-stream-interpretation">Interpreting an event stream</h4>
 
   <p>Streams must be decoded using the <span>UTF-8 decode</span> algorithm.</p>
@@ -94084,6 +94151,8 @@ any-char      = %x0000-0009 / %x000B-000C / %x000E-10FFFF
   <p>For other user agents, the appropriate steps to <span>dispatch the event</span> are
   implementation dependent, but at a minimum they must set the <var>data</var> and <var>event type</var> buffers to the empty string before returning.</p>
 
+  </div>
+
   <div class="example">
 
    <p>The following event stream, once followed by a blank line:</p>
@@ -94169,7 +94238,7 @@ data:&nbsp;test
   </div>
 
 
-  <H4>Authoring notes</h4>
+  <h4>Authoring notes</h4>
 
   <p>Legacy proxy servers are known to, in certain cases, drop HTTP connections after a short
   timeout. To protect against such proxy servers, authors can include a comment line (one starting
@@ -94194,6 +94263,7 @@ data:&nbsp;test
   functionality on a per-page basis, or by sharing a single <code>EventSource</code> object using a
   <span data-x="SharedWorkerGlobalScope">shared worker</span>.</p>
 
+  <div w-nodev>
 
   <h4 id="eventsource-push">Connectionless push and other features</h4>
 
@@ -94303,6 +94373,8 @@ data:&nbsp;test
   consoles whenever an <code data-x="event-error">error</code> event is fired, since little to no
   information can be made available in the events themselves.</p>
 
+  </div>
+
 
   <h3 split-filename="web-sockets" id="network"><dfn>Web sockets</dfn></h3>