Add docs for ActionDispatch::Http::URL methods

Add docs for `extract_domain`, `extract_subdomains`, `extract_subdomain`.

Add doc examples for `url`, `protocol`, `raw_host_with_port`, `host`,
`host_with_port`, `port`, `standard_port`, `standard_port?`, `optional_port`,
`port_string`.

[ci skip]

1 files changed, 109 insertions, 0 deletions

diff --git a/actionpack/lib/action_dispatch/http/url.rb b/actionpack/lib/action_dispatch/http/url.rb
index 22c0de2ac2..001b14ec97 100644
--- a/actionpack/lib/action_dispatch/http/url.rb
+++ b/actionpack/lib/action_dispatch/http/url.rb
@@ -12,10 +12,22 @@ module ActionDispatch
       self.tld_length = 1
 
       class << self
+        # Returns the domain part of a host given the domain level.
+        #
+        #    # Top-level domain example
+        #    extract_domain('www.example.com', 1) # => "example.com"
+        #    # Second-level domain example
+        #    extract_domain('dev.www.example.co.uk', 2) # => "example.co.uk"
         def extract_domain(host, tld_length)
           extract_domain_from(host, tld_length) if named_host?(host)
         end
 
+        # Returns the subdomains of a host as an Array given the domain level.
+        #
+        #    # Top-level domain example
+        #    extract_subdomains('www.example.com', 1) # => ["www"]
+        #    # Second-level domain example
+        #    extract_subdomains('dev.www.example.co.uk', 2) # => ["dev", "www"]
         def extract_subdomains(host, tld_length)
           if named_host?(host)
             extract_subdomains_from(host, tld_length)
@@ -24,6 +36,12 @@ module ActionDispatch
           end
         end
 
+        # Returns the subdomains of a host as a String given the domain level.
+        #
+        #    # Top-level domain example
+        #    extract_subdomain('www.example.com', 1) # => "www"
+        #    # Second-level domain example
+        #    extract_subdomain('dev.www.example.co.uk', 2) # => "dev.www"
         def extract_subdomain(host, tld_length)
           extract_subdomains(host, tld_length).join('.')
         end
@@ -173,16 +191,43 @@ module ActionDispatch
       end
 
       # Returns the complete URL used for this request.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.url # => "http://example.com"
       def url
         protocol + host_with_port + fullpath
       end
 
       # Returns 'https://' if this is an SSL request and 'http://' otherwise.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.protocol # => "http://"
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com', 'HTTPS' => 'on'
+      #   req.protocol # => "https://"
       def protocol
         @protocol ||= ssl? ? 'https://' : 'http://'
       end
 
       # Returns the \host for this request, such as "example.com".
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.raw_host_with_port # => "example.com"
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.raw_host_with_port # => "example.com:8080"
       def raw_host_with_port
         if forwarded = env["HTTP_X_FORWARDED_HOST"]
           forwarded.split(/,\s?/).last
@@ -192,17 +237,44 @@ module ActionDispatch
       end
 
       # Returns the host for this request, such as example.com.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.host # => "example.com"
       def host
         raw_host_with_port.sub(/:\d+$/, '')
       end
 
       # Returns a \host:\port string for this request, such as "example.com" or
       # "example.com:8080".
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.host_with_port # => "example.com"
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.host_with_port # => "example.com:8080"
       def host_with_port
         "#{host}#{port_string}"
       end
 
       # Returns the port number of this request as an integer.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com'
+      #   req.port # => 80
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.port # => 8080
       def port
         @port ||= begin
           if raw_host_with_port =~ /:(\d+)$/
@@ -214,6 +286,13 @@ module ActionDispatch
       end
 
       # Returns the standard \port number for this request's protocol.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.standard_port # => 80
       def standard_port
         case protocol
           when 'https://' then 443
@@ -222,18 +301,48 @@ module ActionDispatch
       end
 
       # Returns whether this request is using the standard port
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.standard_port? # => true
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.standard_port? # => false
       def standard_port?
         port == standard_port
       end
 
       # Returns a number \port suffix like 8080 if the \port number of this request
       # is not the default HTTP \port 80 or HTTPS \port 443.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.optional_port # => nil
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.optional_port # => 8080
       def optional_port
         standard_port? ? nil : port
       end
 
       # Returns a string \port suffix, including colon, like ":8080" if the \port
       # number of this request is not the default HTTP \port 80 or HTTPS \port 443.
+      #
+      #   class Request < Rack::Request
+      #     include ActionDispatch::Http::URL
+      #   end
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:80'
+      #   req.port_string # => ""
+      #
+      #   req = Request.new 'HTTP_HOST' => 'example.com:8080'
+      #   req.port_string # => ":8080"
       def port_string
         standard_port? ? '' : ":#{port}"
       end