ruby-changes:51021
From: stomar <ko1@a...>
Date: Sun, 22 Apr 2018 05:04:11 +0900 (JST)
Subject: [ruby-changes:51021] stomar:r63228 (trunk): Improve docs for URI library
stomar 2018-04-22 05:04:05 +0900 (Sun, 22 Apr 2018) New Revision: 63228 https://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=63228 Log: Improve docs for URI library * lib/uri/generic.rb: [DOC] fix invalid example code to make it syntax highlighted; drop unnecessary `puts', `p'; adapt to current inspect format without Object id; do not display unnecessary return values in examples; fix or prevent unintended description lists; fix broken RDoc; fix grammar and typos. * lib/uri.rb: ditto. * lib/uri/common.rb: ditto. * lib/uri/file.rb: ditto. * lib/uri/ftp.rb: ditto. * lib/uri/http.rb: ditto. * lib/uri/ldap.rb: ditto. * lib/uri/mailto.rb: ditto. * lib/uri/rfc2396_parser.rb: ditto. Modified files: trunk/lib/uri/common.rb trunk/lib/uri/file.rb trunk/lib/uri/ftp.rb trunk/lib/uri/generic.rb trunk/lib/uri/http.rb trunk/lib/uri/ldap.rb trunk/lib/uri/mailto.rb trunk/lib/uri/rfc2396_parser.rb trunk/lib/uri.rb Index: lib/uri/common.rb =================================================================== --- lib/uri/common.rb (revision 63227) +++ lib/uri/common.rb (revision 63228) @@ -61,7 +61,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L61 module_function :make_components_hash end - # module for escaping unsafe characters with codes. + # Module for escaping unsafe characters with codes. module Escape # # == Synopsis @@ -90,13 +90,12 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L90 # require 'uri' # # enc_uri = URI.escape("http://example.com/?a=\11\15") - # p enc_uri # # => "http://example.com/?a=%09%0D" # - # p URI.unescape(enc_uri) + # URI.unescape(enc_uri) # # => "http://example.com/?a=\t\r" # - # p URI.escape("@?@!", "!?") + # URI.escape("@?@!", "!?") # # => "@%3F@%21" # def escape(*arg) @@ -112,7 +111,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L111 # == Args # # +str+:: - # Unescapes the string. + # String to unescape. # # == Description # @@ -125,10 +124,9 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L124 # require 'uri' # # enc_uri = URI.escape("http://example.com/?a=\11\15") - # p enc_uri # # => "http://example.com/?a=%09%0D" # - # p URI.unescape(enc_uri) + # URI.unescape(enc_uri) # # => "http://example.com/?a=\t\r" # def unescape(*arg) @@ -142,7 +140,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L140 include REGEXP @@schemes = {} - # Returns a Hash of the defined schemes + # Returns a Hash of the defined schemes. def self.scheme_list @@schemes end @@ -178,21 +176,21 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L176 # # Splits the string on following parts and returns array with result: # - # * Scheme - # * Userinfo - # * Host - # * Port - # * Registry - # * Path - # * Opaque - # * Query - # * Fragment + # * Scheme + # * Userinfo + # * Host + # * Port + # * Registry + # * Path + # * Opaque + # * Query + # * Fragment # # == Usage # # require 'uri' # - # p URI.split("http://www.ruby-lang.org/") + # URI.split("http://www.ruby-lang.org/") # # => ["http", nil, "www.ruby-lang.org", nil, nil, "/", nil, nil, nil] # def self.split(uri) @@ -215,7 +213,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L213 # # == Raises # - # URI::InvalidURIError + # URI::InvalidURIError:: # Raised if URI given is not a correct one. # # == Usage @@ -223,11 +221,10 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L221 # require 'uri' # # uri = URI.parse("http://www.ruby-lang.org/") - # p uri - # # => #<URI::HTTP:0x202281be URL:http://www.ruby-lang.org/> - # p uri.scheme + # # => #<URI::HTTP http://www.ruby-lang.org/> + # uri.scheme # # => "http" - # p uri.host + # uri.host # # => "www.ruby-lang.org" # # It's recommended to first ::escape the provided +uri_str+ if there are any @@ -255,21 +252,20 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L252 # # require 'uri' # - # p URI.join("http://example.com/","main.rbx") - # # => #<URI::HTTP:0x2022ac02 URL:http://example.com/main.rbx> + # URI.join("http://example.com/","main.rbx") + # # => #<URI::HTTP http://example.com/main.rbx> # - # p URI.join('http://example.com', 'foo') - # # => #<URI::HTTP:0x01ab80a0 URL:http://example.com/foo> + # URI.join('http://example.com', 'foo') + # # => #<URI::HTTP http://example.com/foo> # - # p URI.join('http://example.com', '/foo', '/bar') - # # => #<URI::HTTP:0x01aaf0b0 URL:http://example.com/bar> + # URI.join('http://example.com', '/foo', '/bar') + # # => #<URI::HTTP http://example.com/bar> # - # p URI.join('http://example.com', '/foo', 'bar') - # # => #<URI::HTTP:0x801a92af0 URL:http://example.com/bar> - # - # p URI.join('http://example.com', '/foo/', 'bar') - # # => #<URI::HTTP:0x80135a3a0 URL:http://example.com/foo/bar> + # URI.join('http://example.com', '/foo', 'bar') + # # => #<URI::HTTP http://example.com/bar> # + # URI.join('http://example.com', '/foo/', 'bar') + # # => #<URI::HTTP http://example.com/foo/bar> # def self.join(*str) RFC3986_PARSER.join(*str) @@ -285,7 +281,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L281 # +str+:: # String to extract URIs from. # +schemes+:: - # Limit URI matching to a specific schemes. + # Limit URI matching to specific schemes. # # == Description # @@ -316,6 +312,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L312 # whose scheme is one of the match_schemes. # # == Description + # # Returns a Regexp object which matches to URI-like strings. # The Regexp object returned by this method includes arbitrary # number of capture group (parentheses). Never rely on it's number. @@ -328,7 +325,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L325 # html_string.slice(URI.regexp) # # # remove ftp URIs - # html_string.sub(URI.regexp(['ftp']) + # html_string.sub(URI.regexp(['ftp']), '') # # # You should not rely on the number of parentheses # html_string.scan(URI.regexp) do |*matches| @@ -360,7 +357,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L357 HTML5ASCIIINCOMPAT = defined? Encoding::UTF_7 ? [Encoding::UTF_7, Encoding::UTF_16BE, Encoding::UTF_16LE, Encoding::UTF_32BE, Encoding::UTF_32LE] : [] # :nodoc: - # Encode given +str+ to URL-encoded form data. + # Encodes given +str+ to URL-encoded form data. # # This method doesn't convert *, -, ., 0-9, A-Z, _, a-z, but does convert SP # (ASCII space) to + and converts others to %XX. @@ -368,9 +365,9 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L365 # If +enc+ is given, convert +str+ to the encoding before percent encoding. # # This is an implementation of - # http://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data + # http://www.w3.org/TR/2013/CR-html5-20130806/forms.html#url-encoded-form-data. # - # See URI.decode_www_form_component, URI.encode_www_form + # See URI.decode_www_form_component, URI.encode_www_form. def self.encode_www_form_component(str, enc=nil) str = str.to_s.dup if str.encoding != Encoding::ASCII_8BIT @@ -384,17 +381,17 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L381 str.force_encoding(Encoding::US_ASCII) end - # Decode given +str+ of URL-encoded form data. + # Decodes given +str+ of URL-encoded form data. # # This decodes + to SP. # - # See URI.encode_www_form_component, URI.decode_www_form + # See URI.encode_www_form_component, URI.decode_www_form. def self.decode_www_form_component(str, enc=Encoding::UTF_8) raise ArgumentError, "invalid %-encoding (#{str})" if /%(?!\h\h)/ =~ str str.b.gsub(/\+|%\h\h/, TBLDECWWWCOMP_).force_encoding(enc) end - # Generate URL-encoded form data from given +enum+. + # Generates URL-encoded form data from given +enum+. # # This generates application/x-www-form-urlencoded data defined in HTML5 # from given an Enumerable object. @@ -402,7 +399,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L399 # This internally uses URI.encode_www_form_component(str). # # This method doesn't convert the encoding of given items, so convert them - # before call this method if you want to send data as other than original + # before calling this method if you want to send data as other than original # encoding or mixed encoding data. (Strings which are encoded in an HTML5 # ASCII incompatible encoding are converted to UTF-8.) # @@ -420,7 +417,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L417 # URI.encode_www_form([["q", "ruby"], ["q", "perl"], ["lang", "en"]]) # #=> "q=ruby&q=perl&lang=en" # - # See URI.encode_www_form_component, URI.decode_www_form + # See URI.encode_www_form_component, URI.decode_www_form. def self.encode_www_form(enum, enc=nil) enum.map do |k,v| if v.nil? @@ -441,22 +438,22 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L438 end.join('&') end - # Decode URL-encoded form data from given +str+. + # Decodes URL-encoded form data from given +str+. # # This decodes application/x-www-form-urlencoded data - # and returns array of key-value array. + # and returns an array of key-value arrays. # - # This refers http://url.spec.whatwg.org/#concept-urlencoded-parser , - # so this supports only &-separator, don't support ;-separator. + # This refers http://url.spec.whatwg.org/#concept-urlencoded-parser, + # so this supports only &-separator, and doesn't support ;-separator. # # ary = URI.decode_www_form("a=1&a=2&b=3") - # p ary #=> [['a', '1'], ['a', '2'], ['b', '3']] - # p ary.assoc('a').last #=> '1' - # p ary.assoc('b').last #=> '3' - # p ary.rassoc('a').last #=> '2' - # p Hash[ary] # => {"a"=>"2", "b"=>"3"} + # ary #=> [['a', '1'], ['a', '2'], ['b', '3']] + # ary.assoc('a').last #=> '1' + # ary.assoc('b').last #=> '3' + # ary.rassoc('a').last #=> '2' + # Hash[ary] #=> {"a"=>"2", "b"=>"3"} # - # See URI.decode_www_form_component, URI.encode_www_form + # See URI.decode_www_form_component, URI.encode_www_form. def self.decode_www_form(str, enc=Encoding::UTF_8, separator: '&', use__charset_: false, isindex: false) raise ArgumentError, "the input of #{self.name}.#{__method__} must be ASCII only string" unless str.ascii_only? ary = [] @@ -734,7 +731,7 @@ end # module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/common.rb#L731 module Kernel # - # Returns +uri+ converted to a URI object. + # Returns +uri+ converted to an URI object. # def URI(uri) if uri.is_a?(URI::Generic) Index: lib/uri/ftp.rb =================================================================== --- lib/uri/ftp.rb (revision 63227) +++ lib/uri/ftp.rb (revision 63228) @@ -21,11 +21,11 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L21 # http://tools.ietf.org/html/draft-hoffman-ftp-uri-04 # class FTP < Generic - # A Default port of 21 for URI::FTP + # A Default port of 21 for URI::FTP. DEFAULT_PORT = 21 # - # An Array of the available components for URI::FTP + # An Array of the available components for URI::FTP. # COMPONENT = [ :scheme, @@ -34,7 +34,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L34 ].freeze # - # Typecode is "a", "i" or "d". + # Typecode is "a", "i", or "d". # # * "a" indicates a text file (the FTP command was ASCII) # * "i" indicates a binary file (FTP command IMAGE) @@ -42,8 +42,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L42 # TYPECODE = ['a', 'i', 'd'].freeze - # Typecode prefix - # ';type=' + # Typecode prefix ";type=". TYPECODE_PREFIX = ';type='.freeze def self.new2(user, password, host, port, path, @@ -71,27 +70,29 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L70 # # Creates a new URI::FTP object from components, with syntax checking. # - # The components accepted are +userinfo+, +host+, +port+, +path+ and + # The components accepted are +userinfo+, +host+, +port+, +path+, and # +typecode+. # # The components should be provided either as an Array, or as a Hash # with keys formed by preceding the component names with a colon. # - # If an Array is used, the components must be passed in the order - # [userinfo, host, port, path, typecode] + # If an Array is used, the components must be passed in the + # order <code>[userinfo, host, port, path, typecode]</code>. # # If the path supplied is absolute, it will be escaped in order to - # make it absolute in the URI. Examples: + # make it absolute in the URI. + # + # Examples: # # require 'uri' # - # uri = URI::FTP.build(['user:password', 'ftp.example.com', nil, + # uri1 = URI::FTP.build(['user:password', 'ftp.example.com', nil, # '/path/file.zip', 'i']) - # puts uri.to_s -> ftp://user:password@f.../%2Fpath/file.zip;type=i + # uri1.to_s # => "ftp://user:password@f.../%2Fpath/file.zip;type=i" # # uri2 = URI::FTP.build({:host => 'ftp.example.com', # :path => 'ruby/src'}) - # puts uri2.to_s -> ftp://ftp.example.com/ruby/src + # uri2.to_s # => "ftp://ftp.example.com/ruby/src" # def self.build(args) @@ -128,7 +129,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L129 # required by RFC1738; instead it is treated as per RFC2396. # # Arguments are +scheme+, +userinfo+, +host+, +port+, +registry+, +path+, - # +opaque+, +query+ and +fragment+, in that order. + # +opaque+, +query+, and +fragment+, in that order. # def initialize(scheme, userinfo, host, port, registry, @@ -155,13 +156,13 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L156 end end - # typecode accessor + # typecode accessor. # - # see URI::FTP::COMPONENT + # See URI::FTP::COMPONENT. attr_reader :typecode - # validates typecode +v+, - # returns a +true+ or +false+ boolean + # Validates typecode +v+, + # returns +true+ or +false+. # def check_typecode(v) if TYPECODE.include?(v) @@ -173,9 +174,9 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L174 end private :check_typecode - # Private setter for the typecode +v+ + # Private setter for the typecode +v+. # - # see also URI::FTP.typecode= + # See also URI::FTP.typecode=. # def set_typecode(v) @typecode = v @@ -190,21 +191,20 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L191 # # == Description # - # public setter for the typecode +v+. - # (with validation) + # Public setter for the typecode +v+ + # (with validation). # - # see also URI::FTP.check_typecode + # See also URI::FTP.check_typecode. # # == Usage # # require 'uri' # # uri = URI.parse("ftp://john@f.../my_file.img") - # #=> #<URI::FTP:0x00000000923650 URL:ftp://john@f.../my_file.img> + # #=> #<URI::FTP ftp://john@f.../my_file.img> # uri.typecode = "i" - # # => "i" # uri - # #=> #<URI::FTP:0x00000000923650 URL:ftp://john@f.../my_file.img;type=i> + # #=> #<URI::FTP ftp://john@f.../my_file.img;type=i> # def typecode=(typecode) check_typecode(typecode) @@ -226,29 +226,29 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/ftp.rb#L226 # RFC 1738 specifically states that the path for an FTP URI does not # include the / which separates the URI path from the URI host. Example: # - # +ftp://ftp.example.com/pub/ruby+ + # <code>ftp://ftp.example.com/pub/ruby</code> # # The above URI indicates that the client should connect to - # ftp.example.com then cd pub/ruby from the initial login directory. + # ftp.example.com then cd to pub/ruby from the initial login directory. # # If you want to cd to an absolute directory, you must include an # escaped / (%2F) in the path. Example: # - # +ftp://ftp.example.com/%2Fpub/ruby+ + # <code>ftp://ftp.example.com/%2Fpub/ruby</code> # - # This method will then return "/pub/ruby" + # This method will then return "/pub/ruby". # def path return @path.sub(/^\//,'').sub(/^%2F/,'/') end - # Private setter for the path of the URI::FTP + # Private setter for the path of the URI::FTP. def set_path(v) super("/" + v.sub(/^\//, "%2F")) end protected :set_path - # Returns a String representation of the URI::FTP + # Returns a String representation of the URI::FTP. def to_s save_path = nil if @typecode Index: lib/uri/rfc2396_parser.rb =================================================================== --- lib/uri/rfc2396_parser.rb (revision 63227) +++ lib/uri/rfc2396_parser.rb (revision 63228) @@ -58,7 +58,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/rfc2396_parser.rb#L58 # :startdoc: end # REGEXP - # class that Parses String's into URI's + # Class that Parses String's into URI's. # # It contains a Hash set of patterns and Regexp's that match and validate. # @@ -88,12 +88,12 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/rfc2396_parser.rb#L88 # == Examples # # p = URI::Parser.new(:ESCAPED => "(?:%[a-fA-F0-9]{2}|%u[a-fA-F0-9]{4})") - # u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP:0xb78cf4f8 URL:http://example.jp/%uABCD> + # u = p.parse("http://example.jp/%uABCD") #=> #<URI::HTTP http://example.jp/%uABCD> # URI.parse(u.to_s) #=> raises URI::InvalidURIError # # s = "http://example.com/ABCD" - # u1 = p.parse(s) #=> #<URI::HTTP:0xb78c3220 URL:http://example.com/ABCD> - # u2 = URI.parse(s) #=> #<URI::HTTP:0xb78b6d54 URL:http://example.com/ABCD> + # u1 = p.parse(s) #=> #<URI::HTTP http://example.com/ABCD> + # u2 = URI.parse(s) #=> #<URI::HTTP http://example.com/ABCD> # u1 == u2 #=> true # u1.eql?(u2) #=> false # @@ -109,15 +109,15 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/rfc2396_parser.rb#L109 # The Hash of patterns. # - # see also URI::Parser.initialize_pattern + # See also URI::Parser.initialize_pattern. attr_reader :pattern - # The Hash of Regexp + # The Hash of Regexp. # - # see also URI::Parser.initialize_regexp + # See also URI::Parser.initialize_regexp. attr_reader :regexp - # Returns a split URI against regexp[:ABS_URI] + # Returns a split URI against regexp[:ABS_URI]. def split(uri) case uri when '' @@ -198,14 +198,14 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/rfc2396_parser.rb#L198 # # == Description # - # parses +uri+ and constructs either matching URI scheme object - # (FTP, HTTP, HTTPS, LDAP, LDAPS, or MailTo) or URI::Generic + # Parses +uri+ and constructs either matching URI scheme object + # (file, FTP, HTTP, HTTPS, LDAP, LDAPS, or MailTo) or URI::Generic. # # == Usage # # p = URI::Parser.new # p.parse("ldap://ldap.example.com/dc=example?user=john") - # #=> #<URI::LDAP:0x00000000b9e7e8 URL:ldap://ldap.example.com/dc=example?user=john> + # #=> #<URI::LDAP ldap://ldap.example.com/dc=example?user=john> # def parse(uri) scheme, userinfo, host, port, @@ -231,7 +231,7 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/rfc2396_parser.rb#L231 # # == Description # - # Attempts to parse and merge a set of URIs + # Attempts to parse and merge a set of URIs. # def join(*uris) uris[0] = convert_to_uri(uris[0]) @@ -253,11 +253,11 @@ module URI https://github.com/ruby/ruby/blob/trunk/lib/uri/rfc2396_parser.rb#L253 # # == Description # - # Attempts to parse and merge a set of (... truncated) -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/