Improve documentation for TLS/SSL related options (#226)

* Improve documentation for TLS/SSL related options

Fixes #225

* Fix inconsistent formatting in README

README.md

@@ -401,6 +401,7 @@ The following parameters can be used for tuning HTTP connections:
 The default is five seconds. If a connection has not been used for five seconds, it is automatically reset at next use, in order to avoid attempting to send to a closed connection. Specifiy `nil` to prohibit any timeouts. 
 
 #### read_timeout (integer)
+
 The amount of time allowed between reading two chunks from the socket. The default value is `nil`, which means no timeout. 
 
 #### open_timeout (integer)
@@ -421,27 +422,27 @@ The private key for this client.
 
 #### ca_file (string)
 
-The path to a file containing a PEM-format CA certificate.
+The path to a file containing CA cerificates in PEM format. The plugin will verify the TLS server certificate presented by Splunk against the certificates in this file, unless verification is disabled by the `ssl_insecure` option.
 
 #### ca_path (string)
 
-The path to a directory containing CA certificates in PEM format.
+The path to a directory containing CA certificates in PEM format. The plugin will verify the TLS server certificate presented by Splunk against the certificates in this file, unless verification is disabled by the `ssl_insecure` option.
 
 #### ciphers (array)
 
 List of SSl ciphers allowed.
 
 #### insecure_ssl (bool)
 
-Specifies whether an insecure SSL connection is allowed. If set to false, Splunk does not verify an insecure server certificate. This parameter is set to `false` by default. Ensure parameter `ca_file` is not configured in order to allow insecure SSL connections when this value is set to `true`.
+Specifies whether an insecure SSL connection is allowed. If set to `false` (the default), the plugin will verify the TLS server certificate presented by Splunk against the CA certificates provided by the `ca_file`/`ca_path` options, and reject the certificate if if verification fails.
 
 #### require_ssl_min_version (bool)
 
-When set to true, TLS version 1.1 and above is required.
+When set to `true` (the default), the plugin will require TLSv1.1 or later for its connection to Splunk.
 
 #### consume_chunk_on_4xx_errors (bool)
 
-Specifies whether any 4xx HTTP response status code consumes the buffer chunks. If set to false, Splunk will fail to flush the buffer on such status codes. This parameter is set to `true` by default for backwards compatibility.
+Specifies whether any 4xx HTTP response status code consumes the buffer chunks. If set to `false`, Splunk will fail to flush the buffer on such status codes. This parameter is set to `true` by default for backwards compatibility.
 
 ## About Buffer