From e8a0b94d031a0de45b226babbbd50414a505efe9 Mon Sep 17 00:00:00 2001
From: Rob Wagner <rob@sombia.com>
Date: Thu, 14 Dec 2023 20:44:50 -0500
Subject: [PATCH] Update docs to specify response parts ordering (fixes #11)

---
 README.md                 | 12 ++++++++----
 src/responders/trigger.rs |  9 +++++++++
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index f66de57..a176207 100644
--- a/README.md
+++ b/README.md
@@ -130,10 +130,12 @@ trigger](https://htmx.org/attributes/hx-trigger/) header.
 use axum_htmx::HxResponseTrigger;
 
 // When we load our page, we will trigger any event listeners for "my-event.
-async fn index() -> (&'static str, HxResponseTrigger) {
+async fn index() -> (HxResponseTrigger, &'static str) {
+    // Note: As HxResponseTrigger only implements `IntoResponseParts`, we must
+    // return our trigger first here.
     (
-        "Hello, world!",
         HxResponseTrigger::normal(["my-event", "second-event"]),
+        "Hello, world!",
     )
 }
 ```
@@ -148,7 +150,7 @@ use serde_json::json;
 // instead of the root module.
 use axum_htmx::{HxEvent, HxResponseTrigger};
 
-async fn index() -> (&'static str, HxResponseTrigger) {
+async fn index() -> (HxResponseTrigger, &'static str) {
     let event = HxEvent::new_with_data(
         "my-event",
         // May be any object that implements `serde::Serialize`
@@ -159,7 +161,9 @@ async fn index() -> (&'static str, HxResponseTrigger) {
     )
     .unwrap();
 
-    ("Hello, world!", HxResponseTrigger::normal([event]))
+    // Note: As HxResponseTrigger only implements `IntoResponseParts`, we must
+    // return our trigger first here.
+    (HxResponseTrigger::normal([event]), "Hello, world!")
 }
 ```
 
diff --git a/src/responders/trigger.rs b/src/responders/trigger.rs
index 21c7eb2..7777f1e 100644
--- a/src/responders/trigger.rs
+++ b/src/responders/trigger.rs
@@ -111,6 +111,9 @@ pub enum TriggerMode {
 /// visible ASCII (32-127) when serializing to JSON.
 ///
 /// See <https://htmx.org/headers/hx-trigger/> for more information.
+///
+/// Note: An `HxResponseTrigger` implements `IntoResponseParts` and should be
+/// used before any other response object would consume the response parts.
 #[derive(Debug, Clone)]
 pub struct HxResponseTrigger {
     pub mode: TriggerMode,
@@ -129,18 +132,24 @@ impl HxResponseTrigger {
 
     /// Creates new [normal](https://htmx.org/headers/hx-trigger/) trigger from
     /// events.
+    ///
+    /// See `HxResponseTrigger` for more information.
     pub fn normal<T: Into<HxEvent>>(events: impl IntoIterator<Item = T>) -> Self {
         Self::new(TriggerMode::Normal, events)
     }
 
     /// Creates new [after settle](https://htmx.org/headers/hx-trigger/) trigger
     /// from events.
+    ///
+    /// See `HxResponseTrigger` for more information.
     pub fn after_settle<T: Into<HxEvent>>(events: impl IntoIterator<Item = T>) -> Self {
         Self::new(TriggerMode::AfterSettle, events)
     }
 
     /// Creates new [after swap](https://htmx.org/headers/hx-trigger/) trigger
     /// from events.
+    ///
+    /// See `HxResponseTrigger` for more information.
     pub fn after_swap<T: Into<HxEvent>>(events: impl IntoIterator<Item = T>) -> Self {
         Self::new(TriggerMode::AfterSwap, events)
     }