docs: lua warn about first run checks

Signed-off-by: Josh Soref <2119212+jsoref@users.noreply.github.com>

diff --git a/docs/lua-records/functions.rst b/docs/lua-records/functions.rst
index 45a63a1c258b4d17e10fe0c15578e4108f7c7c63..d0248a88fe5a551686ee95eaa2cc982b70541261 100644 (file)
--- a/docs/lua-records/functions.rst
+++ b/docs/lua-records/functions.rst
@@ -43,6 +43,14 @@ Functions available
 Record creation functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
+  .. _if-first-run:
+
+.. warning::
+  For functions that require network traffic ``if...(..., addresses[...])``,
+  the first time they're called, they effectively treat all addresses as
+  failing which means that whatever fallback behavior is used will apply to
+  that first resolution.
+
 .. function:: ifportup(portnum, addresses[, options])
 
   Simplistic test to see if an IP address listens on a certain port. This will
@@ -52,8 +60,8 @@ Record creation functions
   list IPv4 addresses on an AAAA record, or IPv6 addresses on an A record.
 
   Will return a single address from the set of available addresses. If
-  no address is available, will return a random element of the set of
-  addresses supplied for testing.
+  no address is available (but also :ref:`on the first run <if-first-run>`),
+  will return a random element of the set of addresses supplied for testing.
 
   :param int portnum: The port number to test connections to.
   :param {str} addresses: The list of addresses to check connectivity for.
@@ -72,7 +80,8 @@ Record creation functions
 .. function:: ifurlup(url, addresses[, options])
 
   More sophisticated test that attempts an actual http(s) connection to
-  ``url``. In addition, a list of sets of IP addresses can be supplied. The
+  ``url`` (but results are not used :ref:`on the first run <if-first-run>`).
+  In addition, a list of sets of IP addresses can be supplied. The
   first set with at least one available address is selected. The ``selector`` then
   selects from the subset of available addresses of the selected set.
   An URL is considered available if the HTTP response code is 200 and optionally if