From b3c89169dbf8972e1abe833479b575a165e546de Mon Sep 17 00:00:00 2001
From: Tom L <98499638+expressvpn-tom-l@users.noreply.github.com>
Date: Tue, 17 Oct 2023 14:17:22 +0800
Subject: [PATCH] fixup: update documentation about he_pmtud_state_change_cb_t

---
 include/he.h     |  9 ++++++++-
 public/he.h      | 11 +++++++++--
 src/he/ssl_ctx.h |  2 +-
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/include/he.h b/include/he.h
index ed934495..bc86c156 100644
--- a/include/he.h
+++ b/include/he.h
@@ -528,7 +528,14 @@ typedef he_return_code_t (*he_pmtud_time_cb_t)(he_conn_t *conn, int timeout, voi
  * @param context A pointer to the user defined context
  * @see he_conn_set_context Sets the value of the context pointer
  *
- * Whenever Lightway PMTUD changes state, this function will be called.
+ * Whenever Lightway PMTUD changes state, this function will be called. This callback is
+ * mostly for informational only, there's no hard expectation for the callback to do anything.
+ * However, this callback may be useful for certain application logic which is triggered by the
+ * state changes.
+ *
+ * The host application must register this callback to enable Path MTU discovery.
+ *
+ * @see RFC 8899 for more information about PMTUD state machines.
  */
 typedef he_return_code_t (*he_pmtud_state_change_cb_t)(he_conn_t *conn, he_pmtud_state_t state,
                                                        void *context);
diff --git a/public/he.h b/public/he.h
index ab7dbffb..6d7cf499 100644
--- a/public/he.h
+++ b/public/he.h
@@ -528,7 +528,14 @@ typedef he_return_code_t (*he_pmtud_time_cb_t)(he_conn_t *conn, int timeout, voi
  * @param context A pointer to the user defined context
  * @see he_conn_set_context Sets the value of the context pointer
  *
- * Whenever Lightway PMTUD changes state, this function will be called.
+ * Whenever Lightway PMTUD changes state, this function will be called. This callback is
+ * mostly for informational only, there's no hard expectation for the callback to do anything.
+ * However, this callback may be useful for certain application logic which is triggered by the
+ * state changes.
+ *
+ * The host application must register this callback to enable Path MTU discovery.
+ *
+ * @see RFC 8899 for more information about PMTUD state machines.
  */
 typedef he_return_code_t (*he_pmtud_state_change_cb_t)(he_conn_t *conn, he_pmtud_state_t state,
                                                        void *context);
@@ -1047,7 +1054,7 @@ void he_ssl_ctx_set_populate_network_config_ipv4_cb(
     he_ssl_ctx_t *ctx, he_populate_network_config_ipv4_cb_t pop_network_cb);
 
 /**
- * @brief Sets the function that will be called when Lightway PMTUD changes state
+ * @brief Sets the function that will be called when Lightway PMTUD changes state.
  * @param ctx A pointer to a valid SSL context
  * @param pmtud_state_change_cb The function to be called when Lightway PMTUD changes state
  * @note This callback function is optional if the implementation never intends to use the PMTUD
diff --git a/src/he/ssl_ctx.h b/src/he/ssl_ctx.h
index cb3fd286..7f8a45c6 100644
--- a/src/he/ssl_ctx.h
+++ b/src/he/ssl_ctx.h
@@ -471,7 +471,7 @@ void he_ssl_ctx_set_populate_network_config_ipv4_cb(
     he_ssl_ctx_t *ctx, he_populate_network_config_ipv4_cb_t pop_network_cb);
 
 /**
- * @brief Sets the function that will be called when Lightway PMTUD changes state
+ * @brief Sets the function that will be called when Lightway PMTUD changes state.
  * @param ctx A pointer to a valid SSL context
  * @param pmtud_state_change_cb The function to be called when Lightway PMTUD changes state
  * @note This callback function is optional if the implementation never intends to use the PMTUD