Improvements to the Jetty documentation.

Updated specific module documentation.

Signed-off-by: Simone Bordet <simone.bordet@gmail.com>

jetty-documentation/src/main/asciidoc/operations-guide/modules/module-deploy.adoc

@@ -26,6 +26,8 @@ include::{JETTY_HOME}/modules/deploy.mod[]
 
 Among the configurable properties, the most relevant are:
 
-* `jetty.deploy.monitoredDir`, to change the name of the monitored directory.
+`jetty.deploy.monitoredDir`::
-* `jetty.deploy.scanInterval`, to change the scan period, that is how frequently the `DeploymentManager` wakes up to scan the monitored directory for changes.
+The name of the monitored directory.
+`jetty.deploy.scanInterval`::
+The scan period in seconds, that is how frequently the `DeploymentManager` wakes up to scan the monitored directory for changes.
 Setting `jetty.deploy.scanInterval=0` disabled _hot_ deployment so that only static deployment will be possible (see also xref:og-deploy-hot-static[here] for more information).

jetty-documentation/src/main/asciidoc/operations-guide/modules/module-http.adoc

@@ -24,10 +24,14 @@ include::{JETTY_HOME}/modules/http.mod[tags=documentation]
 
 Among the configurable properties, the most relevant are:
 
-* `jetty.http.port`, default `8080`, is the network port that Jetty listens to for clear-text HTTP/1.1 connections.
+`jetty.http.port`::
-* `jetty.http.idleTimeout`, default `30` seconds, is the amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources.
+The network port that Jetty listens to for clear-text HTTP/1.1 connections -- default `8080`.
-* `jetty.http.acceptors`, default -1 (i.e. an accept heuristic decides the value based on the number of cores), is the number of threads that compete to accept connections.
+`jetty.http.idleTimeout`::
-* `jetty.http.selectors`, default -1 (i.e. a select heuristic decides the value based on the number of cores), is the number of NIO selectors (with an associated thread) that manage connections.
+The amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources -- default `30` seconds.
+`jetty.http.acceptors`::
+The number of threads that compete to accept connections -- default -1 (i.e. an accept heuristic decides the value based on the number of cores).
+`jetty.http.selectors`::
+The number of NIO selectors (with an associated thread) that manage connections -- default -1 (i.e. a select heuristic decides the value based on the number of cores).
 
 [[og-module-http-acceptors]]
 ===== Configuration of Acceptors

jetty-documentation/src/main/asciidoc/operations-guide/modules/module-ssl.adoc

@@ -28,14 +28,14 @@ include::{JETTY_HOME}/modules/ssl.mod[tags=documentation-connector]
 Among the configurable properties, the most relevant are:
 
 `jetty.ssl.port`::
-the network port that Jetty listens to for secure connections -- default `8443`.
+The network port that Jetty listens to for secure connections -- default `8443`.
 `jetty.http.idleTimeout`::
-the amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources -- default `30000` milliseconds.
+The amount of time a connection can be idle (i.e. no bytes received and no bytes sent) until the server decides to close it to save resources -- default `30000` milliseconds.
 `jetty.http.acceptors`::
-the number of threads that compete to accept connections -- default -1 (i.e. an accept heuristic decides the value based on the number of cores).
+The number of threads that compete to accept connections -- default -1 (i.e. an accept heuristic decides the value based on the number of cores).
 Refer to xref:og-module-http-acceptors[this section] for more information about acceptor threads.
 `jetty.http.selectors`::
-the number of NIO selectors (with an associated thread) that manage connections -- default -1 (i.e. a select heuristic decides the value based on the number of cores).
+The number of NIO selectors (with an associated thread) that manage connections -- default -1 (i.e. a select heuristic decides the value based on the number of cores).
 Refer to xref:og-module-http-selectors[this section] for more information about selector threads.
 
 The module properties to configure the KeyStore and TLS parameters are:
@@ -49,19 +49,17 @@ include::{JETTY_HOME}/modules/ssl.mod[tags=documentation-ssl-context]
 
 Among the configurable properties, the most relevant are:
 
-jetty.sslContext.keyStorePath::
+`jetty.sslContext.keyStorePath`::
-the KeyStore path on the file system.
+The KeyStore path on the file system relative to `$JETTY_BASE` -- defaults to `$JETTY_BASE/etc/keystore.p12`.
-If it is a relative path, it is relative to `$JETTY_BASE`.
-Defaults to `$JETTY_BASE/etc/keystore.p12`.
 `jetty.sslContext.keyStorePassword`::
-the KeyStore password, which you want to explicitly configure.
+The KeyStore password, which you want to explicitly configure.
 The password may be obfuscated with the xref:og-password[Jetty Password Tool].
 
 If you need to configure client certificate authentication, you want to configure one of these properties (they are mutually exclusive):
 
 `jetty.sslContext.needClientAuth`::
-whether client certificate authentication should be required.
+Whether client certificate authentication should be required.
 `jetty.sslContext.wantClientAuth`::
-whether client certificate authentication should be requested.
+Whether client certificate authentication should be requested.
 
 If you configure client certificate authentication, you need to configure and distribute a client KeyStore as explained in xref:og-keystore-client-authn[this section].

jetty-documentation/src/main/asciidoc/operations-guide/modules/module-threadpool.adoc

@@ -16,7 +16,10 @@
 
 The `threadpool` module allows you to configure the server-wide thread pool.
 
-// TODO: thread pool per connector should be documented here?
+The thread pool creates threads on demand up to `maxThreads`, and idle them out if they are not used.
+
+Since Jetty uses the thread pool internally to execute critical tasks, it is not recommended to constrain the thread pool to small values of `maxThreads` with the purpose of limiting HTTP request concurrency, as this could very likely cause a server lockup when Jetty needs to run a critical task but there are no threads available.
+Start with the default value of `maxThreads`, and tune for larger values if needed.
 
 The module file is `$JETTY_HOME/modules/threadpool.mod`:
 
@@ -26,4 +29,8 @@ include::{JETTY_HOME}/modules/threadpool.mod[]
 
 Among the configurable properties, the most relevant are:
 
-TODO
+`jetty.threadPool.maxThreads`::
+The max number of threads pooled by the thread pool -- defaults to 200.
+
+`jetty.threadPool.idleTimeout`::
+The time, in milliseconds, after which an idle thread is released from the pool -- defaults to 60000, i.e. 60 seconds.

jetty-server/src/main/config/modules/threadpool.mod

@@ -1,7 +1,5 @@
-# DO NOT EDIT - See: https://www.eclipse.org/jetty/documentation/current/startup-modules.html
-
 [description]
-Enables and configures the Server thread pool.
+Enables and configures the Server ThreadPool.
 
 [depends]
 logging
@@ -10,19 +8,17 @@ logging
 etc/jetty-threadpool.xml
 
 [ini-template]
-
+## Minimum number of pooled threads.
-### Server Thread Pool Configuration
-## Minimum Number of Threads
 #jetty.threadPool.minThreads=10
 
-## Maximum Number of Threads
+## Maximum number of pooled threads.
 #jetty.threadPool.maxThreads=200
 
-## Number of reserved threads (-1 for heuristic)
+## Number of reserved threads (-1 for heuristic).
 #jetty.threadPool.reservedThreads=-1
 
-## Thread Idle Timeout (in milliseconds)
+## Thread idle timeout (in milliseconds).
 #jetty.threadPool.idleTimeout=60000
 
-## Whether to Output a Detailed Dump
+## Whether to output a detailed dump.
 #jetty.threadPool.detailedDump=false