Merge "Improve help text for wsgi options"

nova/conf/wsgi.py

@@ -29,8 +29,15 @@ wsgi_group = cfg.OptGroup(
 api_paste_config = cfg.StrOpt(
     'api_paste_config',
     default="api-paste.ini",
-    help='File name for the paste.deploy config for nova-api',
+    deprecated_group='DEFAULT',
-    deprecated_group='DEFAULT')
+    help="""
+This option represents a file name for the paste.deploy config for nova-api.
+
+Possible values:
+
+ * api-paste.ini (default)
+ * A string representing file name for the paste.deploy config.
+""")
 
 # TODO(sfinucan): It is not possible to rename this to 'log_format'
 # yet, as doing so would cause a conflict if '[DEFAULT] log_format'
@@ -40,73 +47,177 @@ wsgi_log_format = cfg.StrOpt(
     'wsgi_log_format',
     default='%(client_ip)s "%(request_line)s" status: %(status_code)s'
             ' len: %(body_length)s time: %(wall_seconds).7f',
-    help='A python format string that is used as the template to '
+    deprecated_group='DEFAULT',
-         'generate log lines. The following values can be formatted '
+    help="""
-         'into it: client_ip, date_time, request_line, status_code, '
+It represents a python format string that is used as the template to generate
-         'body_length, wall_seconds.',
+log lines. The following values can be formatted into it: client_ip,
-    deprecated_group='DEFAULT')
+date_time, request_line, status_code, body_length, wall_seconds.
+
+This option is used for building custom request loglines.
+
+Possible values:
+
+ * '%(client_ip)s "%(request_line)s" status: %(status_code)s'
+   'len: %(body_length)s time: %(wall_seconds).7f' (default)
+ * Any formatted string formed by specific values.
+""")
 
 secure_proxy_ssl_header = cfg.StrOpt(
     'secure_proxy_ssl_header',
-    help='The HTTP header used to determine the scheme for the '
+    deprecated_group='DEFAULT',
-         'original request, even if it was removed by an SSL '
+    help="""
-         'terminating proxy. Typical value is '
+This option specifies the HTTP header used to determine the scheme for the
-         '"HTTP_X_FORWARDED_PROTO".',
+original request, even if it was removed by an SSL terminating proxy.
-    deprecated_group='DEFAULT')
+Typical value is '"HTTP_X_FORWARDED_PROTO".
+
+It is represented as a tuple with HTTP header/value combination that signifies
+a request is secure.
+
+Possible values:
+
+ * None (default)
+ * https
+""")
 
 ssl_ca_file = cfg.StrOpt(
     'ssl_ca_file',
-    help='CA certificate file to use to verify connecting clients',
+    deprecated_group='DEFAULT',
-    deprecated_group='DEFAULT')
+    help="""
+This option allows setting path to the CA certificate file that should be used
+to verify connecting clients.
+
+Possible values:
+
+ * String representing path to the CA certificate file.
+
+Related options:
+
+ * enabled_ssl_apis
+""")
 
 ssl_cert_file = cfg.StrOpt(
     'ssl_cert_file',
-    help='SSL certificate of API server',
+    deprecated_group='DEFAULT',
-    deprecated_group='DEFAULT')
+    help="""
+This option allows setting path to the SSL certificate of API server.
+
+Possible values:
+
+ * String representing path to the SSL certificate.
+
+Related options:
+
+ * enabled_ssl_apis
+""")
 
 ssl_key_file = cfg.StrOpt(
     'ssl_key_file',
-    help='SSL private key of API server',
+    deprecated_group='DEFAULT',
-    deprecated_group='DEFAULT')
+    help="""
+This option specifies the path to the file where SSL private key of API
+server is stored when SSL is in effect.
+
+Possible values:
+
+ * String representing path to the SSL private key.
+
+Related options:
+
+ * enabled_ssl_apis
+""")
 
 tcp_keepidle = cfg.IntOpt(
     'tcp_keepidle',
+    min=0,
     default=600,
-    help='Sets the value of TCP_KEEPIDLE in seconds for each '
+    deprecated_group='DEFAULT',
-         'server socket. Not supported on OS X.',
+    help="""
-    deprecated_group='DEFAULT')
+This option sets the value of TCP_KEEPIDLE in seconds for each server socket.
+It specifies the duration of time to keep connection active. TCP generates a
+KEEPALIVE transmission for an application that requests to keep connection
+active. Not supported on OS X.
+
+Possible values:
+
+ * 600 (default) or any positive integer representing timeout in seconds.
+
+Related options:
+
+ * keep_alive
+""")
 
 default_pool_size = cfg.IntOpt(
     'default_pool_size',
+    min=0,
     default=1000,
-    help='Size of the pool of greenthreads used by wsgi',
     deprecated_group='DEFAULT',
-    deprecated_name='wsgi_default_pool_size')
+    deprecated_name='wsgi_default_pool_size',
+    help="""
+This option specifies the size of the pool of greenthreads used by wsgi.
+It is possible to limit the number of concurrent connections using this
+option.
+
+Possible values:
+
+ * 1000 (default) or any positive integer.
+""")
 
 max_header_line = cfg.IntOpt(
     'max_header_line',
+    min=0,
     default=16384,
-    help='Maximum line size of message headers to be accepted. '
+    deprecated_group='DEFAULT',
-         'max_header_line may need to be increased when using '
+    help="""
-         'large tokens (typically those generated by the '
+This option specifies the maximum line size of message headers to be accepted.
-         'Keystone v3 API with big service catalogs).',
+max_header_line may need to be increased when using large tokens (typically
-    deprecated_group='DEFAULT')
+those generated by the Keystone v3 API with big service catalogs).
+
+Since TCP is a stream based protocol, in order to reuse a connection, the HTTP
+has to have a way to indicate the end of the previous response and beginning
+of the next. Hence, in a keep_alive case, all messages must have a
+self-defined message length.
+
+Possible values:
+
+ * 16384 (default) or any positive integer.
+""")
 
 keep_alive = cfg.BoolOpt(
     'keep_alive',
     default=True,
-    help='If False, closes the client socket connection explicitly.',
     deprecated_group='DEFAULT',
-    deprecated_name='wsgi_keep_alive')
+    deprecated_name='wsgi_keep_alive',
+    help="""
+This option allows using the same TCP connection to send and receive multiple
+HTTP requests/responses, as opposed to opening a new one for every single
+request/response pair. HTTP keep-alive indicates HTTP connection reuse.
+
+Possible values:
+
+ * True (default) : reuse HTTP connection.
+ * False : closes the client socket connection explicitly.
+
+Related options:
+
+ * tcp_keepidle
+""")
 
 client_socket_timeout = cfg.IntOpt(
     'client_socket_timeout',
+    min=0,
     default=900,
-    help="Timeout for client connections' socket operations. "
+    deprecated_group='DEFAULT',
-         "If an incoming connection is idle for this number of "
+    help="""
-         "seconds it will be closed. A value of '0' means "
+This option specifies the timeout for client connections' socket operations.
-         "wait forever.",
+If an incoming connection is idle for this number of seconds it will be
-    deprecated_group='DEFAULT')
+closed. It indicates timeout on individual read/writes on the socket
+connection.
+
+Possible values:
+
+ * 900 (default) or any positive integer.
+ * 0 : wait forever.
+""")
 
 ALL_OPTS = [api_paste_config,
             wsgi_log_format,