Document variable timeout

src/lib.rs

@@ -30,11 +30,22 @@
 //! ```
 //!
 //! ## Variable Timeout
-//! TODO
+//! Knowing whether or not a terminal supports querying for
+//! foreground and background colors is a tricky business because terminals are
+//! hard to distinguish [^1]. Employing a fixed timeout is not the best options because
+//! the terminal might support the sequence but have a lot of latency (e.g. the user is connected over SSH).
+//!
+//! This library assumes that [terminals support][terminal-survey] the `CSI c` sequence.
+//! Using this, it measures the latency. This measurement then informs the timeout enforced on the actual query.
+//!
+//!
+//! [^1]: Many terminals claim that they are `xterm` by setting `TERM=xterm` or `TERM=xterm-256color`, which makes this even harder.
 //!
 //! ## Comparison with Other Libraries
 //! * termbg: TODO
 //! * dark-light: TODO
+//!
+//! [terminal-survey]: https://github.com/bash/term-color/blob/main/doc/terminal-survey.md
 
 use std::io;
 use std::time::Duration;