Consistent usage of instance/object/value. Fixes rack#2304.

Author: samuel-williams-shopify

SPEC.rdoc

@@ -8,7 +8,7 @@ A Rack application is a Ruby object that responds to +call+. It takes exactly on
 
 == The Request Environment
 
-Incoming HTTP requests are represented using an environment. The environment must be an unfrozen instance of +Hash+. The Rack application is free to modify the environment, but the modified environment should also comply with this specification. All environment keys must be strings.
+Incoming HTTP requests are represented using an environment. The environment must be an unfrozen +Hash+. The Rack application is free to modify the environment, but the modified environment should also comply with this specification. All environment keys must be strings.
 
 === CGI Variables
 
@@ -145,13 +145,13 @@ If present, an array of callables that will be run by the server after the respo
 === The Input Stream
 
 The input stream is an +IO+-like object which contains the raw HTTP request data. When applicable, its external encoding must be <tt>ASCII-8BIT</tt> and it must be opened in binary mode. The input stream must respond to +gets+, +each+, and +read+:
-* +gets+ must be called without arguments and return a string, or +nil+ on <tt>EOF</tt>.
+* +gets+ must be called without arguments and return a +String+, or +nil+ on <tt>EOF</tt>.
 * +read+ behaves like <tt>IO#read</tt>. Its signature is <tt>read([length, [buffer]])</tt>.
   * If given, +length+ must be a non-negative Integer (>= 0) or +nil+, and +buffer+ must be a +String+ and may not be +nil+.
   * If +length+ is given and not +nil+, then this method reads at most +length+ bytes from the input stream.
   * If +length+ is not given or +nil+, then this method reads all data until <tt>EOF</tt>.
   * When <tt>EOF</tt> is reached, this method returns +nil+ if +length+ is given and not +nil+, or +""+ if +length+ is not given or is +nil+.
-  * If +buffer+ is given, then the read data will be placed into +buffer+ instead of a newly created +String+ object.
+  * If +buffer+ is given, then the read data will be placed into +buffer+ instead of a newly created +String+.
 * +each+ must be called without arguments and only yield +String+ values.
 * +close+ can be called on the input stream to indicate that any remaining input is not needed.
 
@@ -173,15 +173,15 @@ Full hijacking only works with <tt>HTTP/1</tt>. Partial hijacking is functionall
 
 Full hijack is used to completely take over an <tt>HTTP/1</tt> connection. It occurs before any headers are written and causes the server to ignore any response generated by the application. It is intended to be used when applications need access to the raw <tt>HTTP/1</tt> connection.
 
-If <tt>rack.hijack</tt> is present in +env+, it must respond to +call+ and return an +IO+ instance which can be used to read and write to the underlying connection using <tt>HTTP/1</tt> semantics and formatting.
+If <tt>rack.hijack</tt> is present in +env+, it must respond to +call+ and return an +IO+ object which can be used to read and write to the underlying connection using <tt>HTTP/1</tt> semantics and formatting.
 
 ==== Partial Hijack
 
 Partial hijack is used for bi-directional streaming of the request and response body. It occurs after the status and headers are written by the server and causes the server to ignore the Body of the response. It is intended to be used when applications need bi-directional streaming.
 
 If <tt>rack.hijack?</tt> is present in +env+ and truthy, an application may set the special response header <tt>rack.hijack</tt> to an object that responds to +call+, accepting a +stream+ argument.
 
-After the response status and headers have been sent, this hijack callback will be invoked with a +stream+ argument which follows the same interface as outlined in "Streaming Body". Servers must ignore the +body+ part of the response tuple when the <tt>rack.hijack</tt> response header is present. Using an empty +Array+ instance is recommended.
+After the response status and headers have been sent, this hijack callback will be invoked with a +stream+ argument which follows the same interface as outlined in "Streaming Body". Servers must ignore the +body+ part of the response tuple when the <tt>rack.hijack</tt> response header is present. Using an empty +Array+ is recommended.
 
 The special response header <tt>rack.hijack</tt> must only be set if the request +env+ has a truthy <tt>rack.hijack?</tt>.
 
@@ -202,12 +202,12 @@ This is an HTTP status. It must be an Integer greater than or equal to 100.
 
 === The Headers
 
-The headers must be a unfrozen +Hash+. The header keys must be +String+ objects. Special headers starting <tt>rack.</tt> are for communicating with the server, and must not be sent back to the client.
+The headers must be an unfrozen +Hash+. The header keys must be +String+ values. Special headers starting <tt>rack.</tt> are for communicating with the server, and must not be sent back to the client.
 
 * The headers must not contain a <tt>"status"</tt> key.
 * Header keys must conform to {RFC7230}[https://tools.ietf.org/html/rfc7230] token specification, i.e. cannot contain non-printable <tt>ASCII</tt>, <tt>DQUOTE</tt> or <tt>(),/:;<=>?@[\]{}</tt>.
 * Header keys must not contain uppercase <tt>ASCII</tt> characters (A-Z).
-* Header values must be either a +String+ value, or an +Array+ of +String+ values, such that each +String+ value must not contain characters with an <tt>ASCII</tt> ordinal below <tt>040</tt> (32).
+* Header values must be either a +String+, or an +Array+ of +String+ values, such that each +String+ must not contain characters with an <tt>ASCII</tt> ordinal below <tt>040</tt> (32).
 
 ==== The <tt>content-type</tt> Header
 
@@ -225,7 +225,7 @@ Setting this value informs the server that it should perform a connection upgrad
 
 === The Body
 
-The Body is typically an +Array+ of +String+ values, an enumerable that yields +String+ values, a +Proc+ instance, or a File-like object.
+The Body is typically an +Array+ of +String+ values, an enumerable that yields +String+ values, a +Proc+, or a +File+-like object.
 
 The Body must respond to +each+ or +call+. It may optionally respond to +to_path+ or +to_ary+. A Body that responds to +each+ is considered to be an Enumerable Body. A Body that responds to +call+ is considered to be a Streaming Body.
 

lib/rack/lint.rb

@@ -138,7 +138,7 @@ def response
       ##
       ## Incoming HTTP requests are represented using an environment. \
       def check_environment(env)
-        ## The environment must be an unfrozen instance of +Hash+. The Rack application is free to modify the environment, but the modified environment should also comply with this specification. \
+        ## The environment must be an unfrozen +Hash+. The Rack application is free to modify the environment, but the modified environment should also comply with this specification. \
         raise LintError, "env #{env.inspect} is not a Hash, but #{env.class}" unless env.kind_of? Hash
         raise LintError, "env should not be frozen, but is" if env.frozen?
 
@@ -502,7 +502,7 @@ def initialize(input)
           @input = input
         end
 
-        ## * +gets+ must be called without arguments and return a string, or +nil+ on <tt>EOF</tt>.
+        ## * +gets+ must be called without arguments and return a +String+, or +nil+ on <tt>EOF</tt>.
         def gets(*args)
           raise LintError, "rack.input#gets called with arguments" unless args.size == 0
 
@@ -520,7 +520,7 @@ def gets(*args)
         ##   * If +length+ is given and not +nil+, then this method reads at most +length+ bytes from the input stream.
         ##   * If +length+ is not given or +nil+, then this method reads all data until <tt>EOF</tt>.
         ##   * When <tt>EOF</tt> is reached, this method returns +nil+ if +length+ is given and not +nil+, or +""+ if +length+ is not given or is +nil+.
-        ##   * If +buffer+ is given, then the read data will be placed into +buffer+ instead of a newly created +String+ object.
+        ##   * If +buffer+ is given, then the read data will be placed into +buffer+ instead of a newly created +String+.
         def read(*args)
           unless args.size <= 2
             raise LintError, "rack.input#read called with too many arguments"
@@ -628,7 +628,7 @@ def check_hijack(env)
           env[RACK_HIJACK] = proc do
             io = original_hijack.call
 
-            ## and return an +IO+ instance which can be used to read and write to the underlying connection using <tt>HTTP/1</tt> semantics and formatting.
+            ## and return an +IO+ object which can be used to read and write to the underlying connection using <tt>HTTP/1</tt> semantics and formatting.
             raise LintError, "rack.hijack must return an IO instance" unless io.is_a?(IO)
 
             io
@@ -656,7 +656,7 @@ def check_hijack_response(headers, env)
             end
           end
           ##
-          ## After the response status and headers have been sent, this hijack callback will be invoked with a +stream+ argument which follows the same interface as outlined in "Streaming Body". Servers must ignore the +body+ part of the response tuple when the <tt>rack.hijack</tt> response header is present. Using an empty +Array+ instance is recommended.
+          ## After the response status and headers have been sent, this hijack callback will be invoked with a +stream+ argument which follows the same interface as outlined in "Streaming Body". Servers must ignore the +body+ part of the response tuple when the <tt>rack.hijack</tt> response header is present. Using an empty +Array+ is recommended.
         else
           ##
           ## The special response header <tt>rack.hijack</tt> must only be set if the request +env+ has a truthy <tt>rack.hijack?</tt>.
@@ -707,7 +707,7 @@ def check_status(status)
       ## === The Headers
       ##
       def check_headers(headers)
-        ## The headers must be a unfrozen +Hash+. \
+        ## The headers must be an unfrozen +Hash+. \
         unless headers.kind_of?(Hash)
           raise LintError, "headers object should be a hash, but isn't (got #{headers.class} as headers)"
         end
@@ -717,7 +717,7 @@ def check_headers(headers)
         end
 
         headers.each do |key, value|
-          ## The header keys must be +String+ objects. \
+          ## The header keys must be +String+ values. \
           unless key.kind_of? String
             raise LintError, "header key must be a string, was #{key.class}"
           end
@@ -733,7 +733,7 @@ def check_headers(headers)
           ## * Header keys must not contain uppercase <tt>ASCII</tt> characters (A-Z).
           raise LintError, "uppercase character in header name: #{key}" if key =~ /[A-Z]/
 
-          ## * Header values must be either a +String+ value, \
+          ## * Header values must be either a +String+, \
           if value.kind_of?(String)
             check_header_value(key, value)
           elsif value.kind_of?(Array)
@@ -746,7 +746,7 @@ def check_headers(headers)
       end
 
       def check_header_value(key, value)
-        ## such that each +String+ value must not contain characters with an <tt>ASCII</tt> ordinal below <tt>040</tt> (32).
+        ## such that each +String+ must not contain characters with an <tt>ASCII</tt> ordinal below <tt>040</tt> (32).
         if value =~ /[\000-\037]/
           raise LintError, "invalid header value #{key}: #{value.inspect}"
         end
@@ -816,7 +816,7 @@ def check_rack_protocol_header(status, headers)
       ##
       ## === The Body
       ##
-      ## The Body is typically an +Array+ of +String+ values, an enumerable that yields +String+ values, a +Proc+ instance, or a File-like object.
+      ## The Body is typically an +Array+ of +String+ values, an enumerable that yields +String+ values, a +Proc+, or a +File+-like object.
       ##
       ## The Body must respond to +each+ or +call+. It may optionally respond to +to_path+ or +to_ary+. A Body that responds to +each+ is considered to be an Enumerable Body. A Body that responds to +call+ is considered to be a Streaming Body.
       ##