[ci skip] Add, clean up docs in ActionDispatch ActionDispatch middleware

actionpack/lib/action_dispatch/middleware/static.rb

@@ -3,15 +3,15 @@
 
 module ActionDispatch
   # This middleware returns a file's contents from disk in the body response.
-  # When initialized it can accept an optional 'Cache-Control' header which
+  # When initialized, it can accept an optional 'Cache-Control' header, which
   # will be set when a response containing a file's contents is delivered.
   #
   # This middleware will render the file specified in `env["PATH_INFO"]`
-  # where the base path is in the +root+ directory. For example if the +root+
-  # is set to `public/` then a request with `env["PATH_INFO"]` of
-  # `assets/application.js` will return a response with contents of a file
+  # where the base path is in the +root+ directory. For example, if the +root+
+  # is set to `public/`, then a request with `env["PATH_INFO"]` of
+  # `assets/application.js` will return a response with the contents of a file
   # located at `public/assets/application.js` if the file exists. If the file
-  # does not exist a 404 "File not Found" response will be returned.
+  # does not exist, a 404 "File not Found" response will be returned.
   class FileHandler
     def initialize(root, cache_control)
       @root          = root.chomp('/')
@@ -20,6 +20,13 @@ def initialize(root, cache_control)
       @file_server = ::Rack::File.new(@root, headers)
     end
 
+
+    # Takes a path to a file. If the file is found, has valid encoding, and has
+    # correct read permissions, the return value is a URI-escaped string
+    # representing the filename. Otherwise, false is returned.
+    #
+    # Used by the `Static` class to check the existence of a valid file
+    # in the server's `public/` directory. (See Static#call)
     def match?(path)
       path = URI.parser.unescape(path)
       return false unless path.valid_encoding?
@@ -88,7 +95,7 @@ def gzip_file_path(path)
   end
 
   # This middleware will attempt to return the contents of a file's body from
-  # disk in the response.  If a file is not found on disk, the request will be
+  # disk in the response. If a file is not found on disk, the request will be
   # delegated to the application stack. This middleware is commonly initialized
   # to serve assets from a server's `public/` directory.
   #