Merge pull request #175 from nobu/doc-uri_parser

Update documents that used `URI::Parser`

Author: nobu

.rdoc_options

@@ -2,3 +2,4 @@ main_page: README.md
 op_dir: _site
 warn_missing_rdoc_ref: true
 title: URI Documentation
+visibility: :private

lib/uri/common.rb

@@ -159,9 +159,11 @@ def self.scheme_list
     Schemes.list
   end
 
+  # :stopdoc:
   INITIAL_SCHEMES = scheme_list
   private_constant :INITIAL_SCHEMES
   Ractor.make_shareable(INITIAL_SCHEMES) if defined?(Ractor)
+  # :startdoc:
 
   # Returns a new object constructed from the given +scheme+, +arguments+,
   # and +default+:
@@ -437,6 +439,8 @@ def self.decode_uri_component(str, enc=Encoding::UTF_8)
     _decode_uri_component(/%\h\h/, str, enc)
   end
 
+  # Returns a string derived from the given string +str+ with
+  # URI-encoded characters matching +regexp+ according to +table+.
   def self._encode_uri_component(regexp, table, str, enc)
     str = str.to_s.dup
     if str.encoding != Encoding::ASCII_8BIT
@@ -451,6 +455,8 @@ def self._encode_uri_component(regexp, table, str, enc)
   end
   private_class_method :_encode_uri_component
 
+  # Returns a string decoding characters matching +regexp+ from the
+  # given \URL-encoded string +str+.
   def self._decode_uri_component(regexp, str, enc)
     raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/.match?(str)
     str.b.gsub(regexp, TBLDECWWWCOMP_).force_encoding(enc)

lib/uri/generic.rb

@@ -284,7 +284,7 @@ def registry # :nodoc:
 
     # Returns the parser to be used.
     #
-    # Unless a URI::Parser is defined, DEFAULT_PARSER is used.
+    # Unless the +parser+ is defined, DEFAULT_PARSER is used.
     #
     def parser
       if !defined?(@parser) || !@parser
@@ -315,7 +315,7 @@ def component
     end
 
     #
-    # Checks the scheme +v+ component against the URI::Parser Regexp for :SCHEME.
+    # Checks the scheme +v+ component against the +parser+ Regexp for :SCHEME.
     #
     def check_scheme(v)
       if v && parser.regexp[:SCHEME] !~ v
@@ -385,7 +385,7 @@ def check_userinfo(user, password = nil)
 
     #
     # Checks the user +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :USERINFO.
+    # and against the +parser+ Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined,
     # with a user component defined.
@@ -409,7 +409,7 @@ def check_user(v)
 
     #
     # Checks the password +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :USERINFO.
+    # and against the +parser+ Regexp for :USERINFO.
     #
     # Can not have a registry or opaque component defined,
     # with a user component defined.
@@ -586,7 +586,7 @@ def decoded_password
 
     #
     # Checks the host +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :HOST.
+    # and against the +parser+ Regexp for :HOST.
     #
     # Can not have a registry or opaque component defined,
     # with a host component defined.
@@ -675,7 +675,7 @@ def hostname=(v)
 
     #
     # Checks the port +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp for :PORT.
+    # and against the +parser+ Regexp for :PORT.
     #
     # Can not have a registry or opaque component defined,
     # with a port component defined.
@@ -748,7 +748,7 @@ def registry=(v) # :nodoc:
 
     #
     # Checks the path +v+ component for RFC2396 compliance
-    # and against the URI::Parser Regexp
+    # and against the +parser+ Regexp
     # for :ABS_PATH and :REL_PATH.
     #
     # Can not have a opaque component defined,
@@ -853,7 +853,7 @@ def query=(v)
 
     #
     # Checks the opaque +v+ component for RFC2396 compliance and
-    # against the URI::Parser Regexp for :OPAQUE.
+    # against the +parser+ Regexp for :OPAQUE.
     #
     # Can not have a host, port, user, or path component defined,
     # with an opaque component defined.
@@ -905,7 +905,7 @@ def opaque=(v)
     end
 
     #
-    # Checks the fragment +v+ component against the URI::Parser Regexp for :FRAGMENT.
+    # Checks the fragment +v+ component against the +parser+ Regexp for :FRAGMENT.
     #
     #
     # == Args

lib/uri/rfc2396_parser.rb

@@ -67,7 +67,7 @@ class RFC2396_Parser
     #
     # == Synopsis
     #
-    #   URI::Parser.new([opts])
+    #   URI::RFC2396_Parser.new([opts])
     #
     # == Args
     #
@@ -86,7 +86,7 @@ class RFC2396_Parser
     #
     # == Examples
     #
-    #   p = URI::Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})")
+    #   p = URI::RFC2396_Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})")
     #   u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP http://example.jp/%uABCD>
     #   URI.parse(u.to_s) #=> raises URI::InvalidURIError
     #
@@ -108,12 +108,12 @@ def initialize(opts = {})
 
     # The Hash of patterns.
     #
-    # See also URI::Parser.initialize_pattern.
+    # See also #initialize_pattern.
     attr_reader :pattern
 
     # The Hash of Regexp.
     #
-    # See also URI::Parser.initialize_regexp.
+    # See also #initialize_regexp.
     attr_reader :regexp
 
     # Returns a split URI against +regexp[:ABS_URI]+.
@@ -202,8 +202,7 @@ def split(uri)
     #
     # == Usage
     #
-    #   p = URI::Parser.new
-    #   p.parse("ldap://ldap.example.com/dc=example?user=john")
+    #   URI::RFC2396_PARSER.parse("ldap://ldap.example.com/dc=example?user=john")
     #   #=> #<URI::LDAP ldap://ldap.example.com/dc=example?user=john>
     #
     def parse(uri)
@@ -244,7 +243,7 @@ def join(*uris)
     # If no +block+ given, then returns the result,
     # else it calls +block+ for each element in result.
     #
-    # See also URI::Parser.make_regexp.
+    # See also #make_regexp.
     #
     def extract(str, schemes = nil)
       if block_given?
@@ -524,6 +523,8 @@ def initialize_regexp(pattern)
       ret
     end
 
+    # Returns +uri+ as-is if it is URI, or convert it to URI if it is
+    # a String.
     def convert_to_uri(uri)
       if uri.is_a?(URI::Generic)
         uri