Add even more documentation

knots/resource-pool.scm

@@ -1252,6 +1252,10 @@ to the current scheduler.
   pool)
 
 (define (destroy-resource-pool pool)
+  "Destroy POOL, preventing any new checkouts.  Blocks until all
+checked-out resources have been returned, running the pool's
+@code{#:destructor} on each.  Any fibers waiting for a resource
+receive @code{&resource-pool-destroyed}."
   (perform-operation
    (choice-operation
     (wrap-operation
@@ -1468,6 +1472,23 @@ available.  Return the resource once PROC has returned."
     (lambda (resource) exp ...)))
 
 (define* (resource-pool-stats pool #:key (timeout 5))
+  "Return an alist of statistics for POOL with the following keys:
+
+@table @code
+@item resources
+Total number of resources currently held by the pool.
+@item available
+Number of resources not currently checked out.
+@item waiters
+Number of fibers currently queued waiting for a resource.
+@item checkout-failure-count
+Cumulative number of checkouts where an exception was raised inside
+the proc.
+@end table
+
+Blocks waiting for the pool fiber to respond.  @code{#:timeout} is
+the number of seconds to wait; defaults to @code{5}.  Raises
+@code{&resource-pool-timeout} if the pool does not respond in time."
   (define channel
     (resource-pool-channel pool))