From fe5b27d78e9118e4ca228a87e917c912b16eb145 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Anarthal=20=28Rub=C3=A9n=20P=C3=A9rez=29?=
 <34971811+anarthal@users.noreply.github.com>
Date: Mon, 14 Oct 2024 17:41:08 +0200
Subject: [PATCH] Document that ping_interval should be >= wait_timeout

Fix defect in connection_pool docs

close #290
---
 include/boost/mysql/connection_pool.hpp |  2 +-
 include/boost/mysql/pool_params.hpp     | 11 ++++++++---
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/include/boost/mysql/connection_pool.hpp b/include/boost/mysql/connection_pool.hpp
index 02fc46efa..1377c3c88 100644
--- a/include/boost/mysql/connection_pool.hpp
+++ b/include/boost/mysql/connection_pool.hpp
@@ -270,7 +270,7 @@ class pooled_connection
  * - Calling \ref connection_pool::async_run.
  * - Calling \ref connection_pool::async_get_connection.
  * - Cancelling \ref async_get_connection by emitting a cancellation signal.
- * - \ref Returning a connection by destroying a \ref pooled_connection or
+ * - Returning a connection by destroying a \ref pooled_connection or
  *   calling \ref pooled_connection::return_without_reset.
  * - Cancelling the pool by calling \ref connection_pool::cancel,
  *   emitting a cancellation signal for \ref async_run, or destroying the
diff --git a/include/boost/mysql/pool_params.hpp b/include/boost/mysql/pool_params.hpp
index 8e708b541..f6b4d7342 100644
--- a/include/boost/mysql/pool_params.hpp
+++ b/include/boost/mysql/pool_params.hpp
@@ -139,10 +139,15 @@ struct pool_params
      * `ping_interval`, a health-check will be performed (using \ref any_connection::async_ping).
      * Pings will be sent with a periodicity of `ping_interval` until the connection
      * is handed to the user, or a ping fails.
-     * \n
+     *
      * Set this interval to zero to disable pings.
-     * \n
-     * This value must not be negative.
+     *
+     * This value must not be negative. It should be bigger than the server's
+     * idle timeout (as determined by the
+     * <a
+     * href="https://dev.mysql.com/doc/refman/8.4/en/server-system-variables.html#sysvar_wait_timeout">wait_timeout</a>
+     * session variable). Otherwise, the server might close connections
+     * without the pool detecting it.
      */
     std::chrono::steady_clock::duration ping_interval{std::chrono::hours(1)};