From 16313be447f862f52dfa78d89e251d493424cf1f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=90=B4=E6=9D=A8=E5=B8=86?=
 <39647285+leno23@users.noreply.github.com>
Date: Sun, 17 May 2026 16:41:49 +0800
Subject: [PATCH] docs(axum-extra): clarify cookie-key-expansion for
 Key::derive_from (fixes #2646) (#3769)

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 axum-extra/src/extract/cookie/mod.rs | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/axum-extra/src/extract/cookie/mod.rs b/axum-extra/src/extract/cookie/mod.rs
index 372a2212..10af3bfc 100644
--- a/axum-extra/src/extract/cookie/mod.rs
+++ b/axum-extra/src/extract/cookie/mod.rs
@@ -1,6 +1,12 @@
 //! Cookie parsing and cookie jar management.
 //!
 //! See [`CookieJar`], [`SignedCookieJar`], and [`PrivateCookieJar`] for more details.
+//!
+//! ## `Key::derive_from`
+//!
+//! The [`Key::derive_from`] method is provided by the underlying [`cookie`] crate, whose docs
+//! refer to the `key-expansion` feature. In `axum-extra`, enable **`cookie-key-expansion`**
+//! instead (see the [crate-level feature list](crate#feature-flags)).
 
 use axum_core::{
     extract::FromRequestParts,
@@ -25,7 +31,12 @@ pub use self::signed::SignedCookieJar;
 
 pub use cookie::{Cookie, Expiration, SameSite};
 
+/// Cookie signing and encryption key.
+///
+/// When using [`Key::derive_from`], enable the **`cookie-key-expansion`** feature on
+/// `axum-extra` (not `key-expansion` from the [`cookie`] crate).
 #[cfg(any(feature = "cookie-signed", feature = "cookie-private"))]
+#[doc(inline)]
 pub use cookie::Key;
 
 /// Extractor that grabs cookies from the request and manages the jar.