Improve RDoc documentation of ActionDispatch::SSL

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.

guides/source/configuring.md

@@ -104,7 +104,7 @@ application. Accepts a valid week day symbol (e.g. `:monday`).
 you don't want shown in the logs, such as passwords or credit card
 numbers. New applications filter out passwords by adding the following `config.filter_parameters+=[:password]` in `config/initializers/filter_parameter_logging.rb`.
 
-* `config.force_ssl` forces all requests to be served used HTTPS by using the `ActionDispatch::SSL` middleware. This can be configured by setting `config.ssl_options` - see the [ActionDispatch::SSL documentation](http://edgeapi.rubyonrails.org/classes/ActionDispatch/SSL.html) for details.
+* `config.force_ssl` forces all requests to be served over HTTPS by using the `ActionDispatch::SSL` middleware. This can be configured by setting `config.ssl_options` - see the [ActionDispatch::SSL documentation](http://edgeapi.rubyonrails.org/classes/ActionDispatch/SSL.html) for details.
 
 * `config.log_formatter` defines the formatter of the Rails logger. This option defaults to an instance of `ActiveSupport::Logger::SimpleFormatter` for all modes except production, where it defaults to `Logger::Formatter`.