From 9344d27cfadf17a1f4318745b1f5484f17b488f5 Mon Sep 17 00:00:00 2001
From: Kai Jewson <kai.jewson@gmail.com>
Date: Sun, 12 Dec 2021 15:56:07 +0000
Subject: [PATCH] Improve documentation of `sse::Event` (#601)

---
 axum/src/response/sse.rs | 48 ++++++++++++++++++++++++++++++----------
 1 file changed, 36 insertions(+), 12 deletions(-)

diff --git a/axum/src/response/sse.rs b/axum/src/response/sse.rs
index 33c61650..8a37d00b 100644
--- a/axum/src/response/sse.rs
+++ b/axum/src/response/sse.rs
@@ -181,8 +181,13 @@ enum DataType {
 }
 
 impl Event {
-    /// Set Server-sent event data
-    /// data field(s) ("data:<content>")
+    /// Set the event's data data field(s) (`data:<content>`)
+    ///
+    /// Newlines in `data` will automatically be broken across `data:` fields.
+    ///
+    /// This corresponds to [`MessageEvent`'s data field].
+    ///
+    /// [`MessageEvent`'s data field]: https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/data
     pub fn data<T>(mut self, data: T) -> Event
     where
         T: Into<String>,
@@ -191,8 +196,11 @@ impl Event {
         self
     }
 
-    /// Set Server-sent event data
-    /// data field(s) ("data:<content>")
+    /// Set the event's data field to a value serialized as unformatted JSON (`data:<content>`).
+    ///
+    /// This corresponds to [`MessageEvent`'s data field].
+    ///
+    /// [`MessageEvent`'s data field]: https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/data
     #[cfg(feature = "json")]
     #[cfg_attr(docsrs, doc(cfg(feature = "json")))]
     pub fn json_data<T>(mut self, data: T) -> Result<Event, serde_json::Error>
@@ -203,8 +211,9 @@ impl Event {
         Ok(self)
     }
 
-    /// Set Server-sent event comment
-    /// Comment field (":<comment-text>")
+    /// Set the event's comment field (`:<comment-text>`).
+    ///
+    /// This field will be ignored by most SSE clients.
     pub fn comment<T>(mut self, comment: T) -> Event
     where
         T: Into<String>,
@@ -213,8 +222,15 @@ impl Event {
         self
     }
 
-    /// Set Server-sent event event
-    /// Event name field ("event:<event-name>")
+    /// Set the event's name field (`event:<event-name>`).
+    ///
+    /// This corresponds to the `type` parameter given when calling `addEventListener` on an
+    /// [`EventSource`]. For example, `.event("update")` should correspond to
+    /// `.addEventListener("update", ...)`. If no event type is given, browsers will fire a
+    /// [`message` event] instead.
+    ///
+    /// [`EventSource`]: https://developer.mozilla.org/en-US/docs/Web/API/EventSource
+    /// [`message` event]: https://developer.mozilla.org/en-US/docs/Web/API/EventSource/message_event
     pub fn event<T>(mut self, event: T) -> Event
     where
         T: Into<String>,
@@ -223,15 +239,23 @@ impl Event {
         self
     }
 
-    /// Set Server-sent event retry
-    /// Retry timeout field ("retry:<timeout>")
+    /// Set the event's retry timeout field (`retry:<timeout>`).
+    ///
+    /// This sets how long clients will wait before reconnecting if they are disconnected from the
+    /// SSE endpoint. Note that this is just a hint: clients are free to wait for longer if they
+    /// wish, such as if they implement exponential backoff.
     pub fn retry(mut self, duration: Duration) -> Event {
         self.retry = Some(duration);
         self
     }
 
-    /// Set Server-sent event id
-    /// Identifier field ("id:<identifier>")
+    /// Set the event's identifier field (`id:<identifier>`).
+    ///
+    /// This corresponds to [`MessageEvent`'s `lastEventId` field]. If no ID is in the event itself,
+    /// the browser will set that field to the last known message ID, starting with the empty
+    /// string.
+    ///
+    /// [`MessageEvent`'s `lastEventId` field]: https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/lastEventId
     pub fn id<T>(mut self, id: T) -> Event
     where
         T: Into<String>,