Amend comments for rest module "pool" to reflect code behaviour

diff --git a/raddb/mods-available/rest b/raddb/mods-available/rest
index de426d2adbbd029ffcaf1b6ee4d15cc45a2a028c..014b8907873ce0661d45c9f1e2d7f3e2d8fd7a94 100644 (file)
--- a/raddb/mods-available/rest
+++ b/raddb/mods-available/rest
@@ -396,45 +396,47 @@ rest {
        #
        pool {
                #
-               #  start:: Connections to create during module instantiation.
-               #  If the server cannot create specified number of connections
+               #  start:: Handles to create during module instantiation.
+               #  If the server cannot create specified number of handles
                #  during instantiation it will exit.
                #
-               #  Set to `0` to allow the server to start without the web service
-               #  being available.
+               #  Set to `0` to allow the server to start without allocating
+               #  any connection handles.
                #
                start = 20
 
                #
-               #  min:: Minimum number of connections to keep open.
+               #  min:: Minimum number of handles to keep allocated.
                #
                min = 1
 
                #
-               #  max:: Maximum number of connections.
+               #  max:: Maximum number of handles.
                #
-               #  If these connections are all in use and a new one
-               #  is requested, the request will NOT get a connection.
+               #  If these handles are all in use and a new one
+               #  is requested, the request will NOT get a handle.
                #
-               #  Setting `max` to LESS than the number of threads means
-               #  that some threads may starve, and you will see errors
-               #  like 'No connections available and at max connection limit'
+               #  Since http requests are performed asynchronously, this
+               #  max represents the maximum number of outstanding requests
+               #  there can be per-thread.
                #
-               #  Setting `max` to MORE than the number of threads means
-               #  that there are more connections than necessary.
+               #  Setting `max` to LESS than the number of potential outstanding
+               #  requests per-thread means that some threads may starve,
+               #  and you will see errors like
+               #  'No connections available and at max connection limit'
                #
                max = 50
 
                #
-               #  spare:: Spare connections to be left idle.
+               #  spare:: Spare handles to be left idle.
                #
-               #  NOTE: Idle connections WILL be closed if `idle_timeout`
+               #  NOTE: Idle handles WILL be freed if `idle_timeout`
                #  is set.  This should be less than or equal to `max` above.
                #
                spare = 1
 
                #
-               #  uses:: Number of uses before the connection is closed.
+               #  uses:: Number of uses before the handle is freed.
                #
                #  NOTE: `0` means "infinite".
                #