From 537b58c431946ba34146743fc8be4fd671aac6d4 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sun, 26 Apr 2026 18:35:04 -0500
Subject: docs: explain mode-line state and update flow

Four variables hold the mode-line's runtime state: the cache, the rendered string, the stale-render flag, and the refresh timer. They get updated in a specific order across three different functions. Anyone reading `wttrin--mode-line-tooltip` for the first time hits a clever bit on every hover: the tooltip re-evaluates staleness and triggers a re-render of the icon if it flipped. Without a comment that ties this to the rest of the update flow, you have to trace through three other functions to understand why.

The new comment block above the defvars lays out the order and the hover-driven re-render in one place, so future readers don't have to reconstruct it from the call graph.
---
 wttrin.el | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/wttrin.el b/wttrin.el
index b117bf3..3caa178 100644
--- a/wttrin.el
+++ b/wttrin.el
@@ -197,6 +197,26 @@ Set this to t BEFORE loading wttrin, typically in your init file:
 (defvar wttrin--force-refresh nil
   "When non-nil, bypass cache on next fetch.")
 
+;;; Mode-line state and update flow
+;;
+;; The state lives in four variables (defined below): the cache as source
+;; of truth, the rendered string for `global-mode-string', a stale-render
+;; flag, and the refresh timer.
+;;
+;; Normal update path:
+;;   `wttrin--mode-line-fetch-weather' updates `wttrin--mode-line-cache'
+;;   and then calls `wttrin--mode-line-update-display', which reads the
+;;   cache, decides staleness via `wttrin--mode-line-stale-p', and writes
+;;   both `wttrin-mode-line-string' and `wttrin--mode-line-rendered-stale'.
+;;
+;; Tooltip-driven re-render:
+;;   `wttrin--mode-line-tooltip' fires on every mouse hover.  It
+;;   re-evaluates staleness against the current cache age and, if that
+;;   flips relative to `wttrin--mode-line-rendered-stale', calls
+;;   `wttrin--mode-line-update-display' to refresh dimming.  This keeps
+;;   the tooltip age and emoji color in sync when a fetch has been
+;;   failing for a while.
+
 (defvar wttrin-mode-line-string nil
   "Mode-line string showing weather for favorite location.")
 ;; Emacs strips text properties from mode-line strings unless the
-- 
cgit v1.2.3