Improve RDoc documentation of ActionDispatch::SSL

1 files changed, 14 insertions, 12 deletions

diff --git a/actionpack/lib/action_dispatch/middleware/ssl.rb b/actionpack/lib/action_dispatch/middleware/ssl.rb
index 47f475559a..8f8f1bab8b 100644
--- a/actionpack/lib/action_dispatch/middleware/ssl.rb
+++ b/actionpack/lib/action_dispatch/middleware/ssl.rb
@@ -1,19 +1,21 @@
 module ActionDispatch
-  # This middleware is added to the stack when `config.force_ssl = true`.
-  # It does three jobs to enforce secure HTTP requests:
+  # This middleware is added to the stack when `config.force_ssl = true`, and is passed
+  # the options set in `config.ssl_options`. It does three jobs to enforce secure HTTP
+  # requests:
   #
-  #   1. TLS redirect. http:// requests are permanently redirected to https://
-  #      with the same URL host, path, etc. Pass `:host` and/or `:port` to
-  #      modify the destination URL. This is always enabled.
+  #   1. TLS redirect: Permanently redirects http:// requests to https://
+  #      with the same URL host, path, etc. This is always enabled. Set
+  #      `config.ssl_options` to modify the destination URL
+  #      (e.g. `redirect: { host: "secure.widgets.com", port: 8080 }`)
   #
-  #   2. Secure cookies. Sets the `secure` flag on cookies to tell browsers they
+  #   2. Secure cookies: Sets the `secure` flag on cookies to tell browsers they
   #      mustn't be sent along with http:// requests. This is always enabled.
   #
-  #   3. HTTP Strict Transport Security (HSTS). Tells the browser to remember
+  #   3. HTTP Strict Transport Security (HSTS): Tells the browser to remember
   #      this site as TLS-only and automatically redirect non-TLS requests.
   #      Enabled by default. Pass `hsts: false` to disable.
   #
-  # Configure HSTS with `hsts: { … }`:
+  # Set `config.ssl_options` with `hsts: { … }` to configure HSTS:
   #   * `expires`: How long, in seconds, these settings will stick. Defaults to
   #     `180.days` (recommended). The minimum required to qualify for browser
   #     preload lists is `18.weeks`.
@@ -26,10 +28,10 @@ module ActionDispatch
   #     gap, browser vendors include a baked-in list of HSTS-enabled sites.
   #     Go to https://hstspreload.appspot.com to submit your site for inclusion.
   #
-  # Disabling HSTS: To turn off HSTS, omitting the header is not enough.
-  # Browsers will remember the original HSTS directive until it expires.
-  # Instead, use the header to tell browsers to expire HSTS immediately.
-  # Setting `hsts: false` is a shortcut for `hsts: { expires: 0 }`.
+  # To turn off HSTS, omitting the header is not enough. Browsers will remember the
+  # original HSTS directive until it expires. Instead, use the header to tell browsers to
+  # expire HSTS immediately. Setting `hsts: false` is a shortcut for
+  # `hsts: { expires: 0 }`.
   class SSL
     # Default to 180 days, the low end for https://www.ssllabs.com/ssltest/
     # and greater than the 18-week requirement for browser preload lists.