gen_server: docs — disambiguate client call deadline from server idle timeout (RFC 015 §7)

src/gen_server.rs

@@ -43,11 +43,29 @@
 //! one. Keep it cheap and non-blocking: it may run mid-unwind, and a panic
 //! inside it during an unwind aborts the process (a double panic).
 //!
+//! ## Time (timers and idle)
+//!
+//! A server arms timers through a [`TimerHandle`] cloned from the [`ServerCtx`]
+//! in `init` and stored on the state — the same shape as [`Watcher`] for
+//! monitors. [`arm_after`](TimerHandle::arm_after) is a one-shot,
+//! [`tick_every`](TimerHandle::tick_every) a periodic; both fire into
+//! [`handle_timer`](GenServer::handle_timer) at *system priority* (above infos
+//! and the inbox, by arm position), and [`cancel`](TimerHandle::cancel) carries
+//! the substrate's race signal. Separately, [`ServerCtx::idle_after`] sets a
+//! receive-timeout window: quiet for the whole window fires
+//! [`handle_idle`](GenServer::handle_idle).
+//!
+//! Two unrelated things share the word *timeout*: the server-side **idle /
+//! receive timeout** above, and the client-side **call deadline**
+//! ([`ServerRef::call_timeout`]) — how long a caller waits for a reply. They sit
+//! on different axes and never interact (RFC 015 §7).
+//!
 //! ## Not here (yet)
 //!
 //! No dynamic info subscription: the info-channel set is fixed at start.
 //! Revisit against a real consumer. (Monitor `Down` forwarding is dynamic —
 //! see `handle_down` — because monitors are inherently created at runtime.)
+//! The idle window is likewise set once, in `init` (RFC 015 §4.4).
 
 use crate::channel::{channel, select, select_timeout, Receiver, RecvTimeoutError, Selectable, Sender};
 use crate::monitor::{demonitor, monitor, Down, Monitor};
@@ -199,6 +217,13 @@ impl<G: GenServer> ServerRef<G> {
     /// Bounded synchronous request-reply: like [`call`](Self::call), but
     /// gives up after `timeout`, returning [`CallTimeoutError::Timeout`].
     ///
+    /// This `timeout` is a **client-side call deadline** — how long *this caller*
+    /// waits for a reply — and is wholly separate from the server-side idle /
+    /// receive timeout ([`ServerCtx::idle_after`] →
+    /// [`GenServer::handle_idle`]), which measures quiet on the *server's* inbox.
+    /// Same word ("timeout"), two different axes (RFC 015 §7); neither touches
+    /// the other.
+    ///
     /// The roadmap sketched this as monitor + wait-reply-or-Down + demonitor;
     /// that machinery is unnecessary here because server death is already
     /// observable on the reply channel itself — the reply sender is dropped