* lib/uri.rb: Documented (thanks Dmitry V. Sabanin).

 * lib/uri/common.rb: Ditto.
 * lib/uri/ftp.rb: Ditto.
 * lib/uri/generic.rb: Ditto.
 * lib/uri/http.rb: Ditto.
 * lib/uri/https.rb: Ditto.
 * lib/uri/ldap.rb: Ditto.
 * lib/uri/mailto.rb: Ditto.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@6015 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 99 insertions, 133 deletions

diff --git a/lib/uri/mailto.rb b/lib/uri/mailto.rb
index 3f2439ed34..0c93ae1c0d 100644
--- a/lib/uri/mailto.rb
+++ b/lib/uri/mailto.rb
@@ -1,35 +1,26 @@
 #
-# $Id$
+# = uri/mailto.rb
 #
-# Copyright (c) 2001 akira yamada <akira@ruby-lang.org>
-# You can redistribute it and/or modify it under the same term as Ruby.
+# Author:: Akira Yamada <akira@ruby-lang.org>
+# License:: You can redistribute it and/or modify it under the same term as Ruby.
+# Revision:: $Id$
 #
 
 require 'uri/generic'
 
 module URI
 
-=begin
-
-== URI::MailTo
-
-=== Super Class
-
-((<URI::Generic>))
-
-=end
-
+  #
   # RFC2368, The mailto URL scheme
+  #
   class MailTo < Generic
     include REGEXP
 
     DEFAULT_PORT = nil
 
-    COMPONENT = [
-      :scheme,
-      :to, :headers
-    ].freeze
+    COMPONENT = [ :scheme, :to, :headers ].freeze
 
+    # :stopdoc:
     #  "hname" and "hvalue" are encodings of an RFC 822 header name and
     #  value, respectively. As with "to", all URL reserved characters must
     #  be encoded.
@@ -52,7 +43,7 @@ module URI
     # to         =  #mailbox
     # mailtoURL  =  "mailto:" [ to ] [ headers ]
     MAILBOX_PATTERN = "(?:#{PATTERN::ESCAPED}|[^(),%?=&])".freeze
-    MAILTO_REGEXP = Regexp.new("
+    MAILTO_REGEXP = Regexp.new(" # :nodoc:
       \\A
       (#{MAILBOX_PATTERN}*?)                          (?# 1: to)
       (?:
@@ -61,63 +52,62 @@ module URI
       )?
       (?:
         \\#
-	(#{PATTERN::FRAGMENT})                        (?# 3: fragment)
+        (#{PATTERN::FRAGMENT})                        (?# 3: fragment)
       )?
       \\z
     ", Regexp::EXTENDED, 'N').freeze
+    # :startdoc:
 
-=begin
-
-=== Class Methods
-
---- URI::MailTo::build
-    Create a new URI::MailTo object from components of URI::MailTo
-    with check.  It is to and headers. It provided by an Array of a
-    Hash. You can provide headers as an String like
-    "subject=subscribe&cc=addr" or an Array like [["subject",
-    "subscribe"], ["cc", "addr"]]
-
---- URI::MailTo::new
-    Create a new URI::MailTo object from ``generic'' components with
-    no check. Because, this method is usually called from URI::parse
-    and the method checks validity of each components.
-
-=end
-
+    #
+    # == Description
+    #
+    # Creates a new URI::MailTo object from components of URI::MailTo
+    # with check.  It is to and headers. It provided by an Array of a
+    # Hash. You can provide headers as String like
+    # "subject=subscribe&cc=addr" or Array like [["subject",
+    # "subscribe"], ["cc", "addr"]]
+    #
     def self.build(args)
       tmp = Util::make_components_hash(self, args)
 
       if tmp[:to]
-	tmp[:opaque] = tmp[:to]
+        tmp[:opaque] = tmp[:to]
       else
-	tmp[:opaque] = ''
+        tmp[:opaque] = ''
       end
 
       if tmp[:headers]
-	tmp[:opaque] << '?'
-
-	if tmp[:headers].kind_of?(Array)
-	  tmp[:opaque] << tmp[:headers].collect { |x|
-	    if x.kind_of?(Array)
-	      x[0] + '=' + x[1..-1].to_s
-	    else
-	      x.to_s
-	    end
-	  }.join('&')
-
-	elsif tmp[:headers].kind_of?(Hash)
-	  tmp[:opaque] << tmp[:headers].collect { |h,v|
-	    h + '=' + v
-	  }.join('&')
-
-	else
-	  tmp[:opaque] << tmp[:headers].to_s
-	end
+        tmp[:opaque] << '?'
+
+        if tmp[:headers].kind_of?(Array)
+          tmp[:opaque] << tmp[:headers].collect { |x|
+            if x.kind_of?(Array)
+              x[0] + '=' + x[1..-1].to_s
+            else
+              x.to_s
+            end
+          }.join('&')
+
+        elsif tmp[:headers].kind_of?(Hash)
+          tmp[:opaque] << tmp[:headers].collect { |h,v|
+            h + '=' + v
+          }.join('&')
+
+        else
+          tmp[:opaque] << tmp[:headers].to_s
+        end
       end
 
       return super(tmp)
     end
 
+    #
+    # == Description
+    #
+    # Creates a new URI::MailTo object from ``generic'' components with
+    # no check. Because, this method is usually called from URI::parse
+    # and the method checks validity of each components.
+    #
     def initialize(*arg)
       super(*arg)
 
@@ -125,43 +115,29 @@ module URI
       @headers = []
 
       if MAILTO_REGEXP =~ @opaque
- 	if arg[-1]
-	  self.to = $1
-	  self.headers = $2
-	else
-	  set_to($1)
-	  set_headers($2)
-	end
+         if arg[-1]
+          self.to = $1
+          self.headers = $2
+        else
+          set_to($1)
+          set_headers($2)
+        end
 
       else
-	raise InvalidComponentError,
-	  "unrecognised opaque part for mailtoURL: #{@opaque}"
+        raise InvalidComponentError,
+          "unrecognised opaque part for mailtoURL: #{@opaque}"
       end
     end
     attr_reader :to
     attr_reader :headers
 
-=begin
-
-=== Instance Methods
-
---- URI::MailTo#to
-
---- URI::MailTo#to=(v)
-
-=end
-
-    #
-    # methods for to
-    #
-
     def check_to(v)
       return true unless v
       return true if v.size == 0
 
       if OPAQUE !~ v || /\A#{MAILBOX_PATTERN}*\z/o !~ v
-	raise InvalidComponentError,
-	  "bad component(expected opaque component): #{v}"
+        raise InvalidComponentError,
+          "bad component(expected opaque component): #{v}"
       end
 
       return true
@@ -179,26 +155,14 @@ module URI
       v
     end
 
-=begin
-
---- URI::MailTo#headers
-
---- URI::MailTo#headers=(v)
-
-=end
-
-    #
-    # methods for headers
-    #
-
     def check_headers(v)
       return true unless v
       return true if v.size == 0
 
       if OPAQUE !~ v || 
-	  /\A(#{HEADER_PATTERN}(?:\&#{HEADER_PATTERN})*)\z/o !~ v
-	raise InvalidComponentError,
-	  "bad component(expected opaque component): #{v}"
+          /\A(#{HEADER_PATTERN}(?:\&#{HEADER_PATTERN})*)\z/o !~ v
+        raise InvalidComponentError,
+          "bad component(expected opaque component): #{v}"
       end
 
       return true
@@ -208,9 +172,9 @@ module URI
     def set_headers(v)
       @headers = []
       if v
-	v.scan(HEADER_REGEXP) do |x|
-	  @headers << x.split(/=/o, 2)
-	end
+        v.scan(HEADER_REGEXP) do |x|
+          @headers << x.split(/=/o, 2)
+        end
       end
     end
     protected :set_headers
@@ -223,42 +187,44 @@ module URI
 
     def to_s
       @scheme + ':' + 
-	if @to 
-	  @to
-	else
-	  ''
-	end + 
-	if @headers.size > 0
-	  '?' + @headers.collect{|x| x.join('=')}.join('&')
-	else
-	  ''
-	end +
-	if @fragment
-	  '#' + @fragment
-	else
-	  ''
-	end
+        if @to 
+          @to
+        else
+          ''
+        end + 
+        if @headers.size > 0
+          '?' + @headers.collect{|x| x.join('=')}.join('&')
+        else
+          ''
+        end +
+        if @fragment
+          '#' + @fragment
+        else
+          ''
+        end
     end
-
-=begin
-
---- URI::MailTo#to_mailtext
-
-=end
+    #
+    # == Usage
+    #   require 'uri'
+    #
+    #   uri = URI.parse("mailto:ruby-list@ruby-lang.org?Subject=subscribe&cc=myaddr")
+    #   uri.to_mailtext
+    #   # => "To: ruby-list@ruby-lang.org\nSubject: subscribe\nCc: myaddr\n\n\n"
+    #
     def to_mailtext
       to = URI::unescape(@to)
       head = ''
       body = ''
       @headers.each do |x|
-	case x[0]
-	when 'body'
-	  body = URI::unescape(x[1])
-	when 'to'
-	  to << ', ' + URI::unescape(x[1])
-	else
-	  head << URI::unescape(x[0]).capitalize + ': ' +
-	    URI::unescape(x[1])  + "\n"
-	end
+        case x[0]
+        when 'body'
+          body = URI::unescape(x[1])
+        when 'to'
+          to << ', ' + URI::unescape(x[1])
+        else
+          head << URI::unescape(x[0]).capitalize + ': ' +
+            URI::unescape(x[1])  + "\n"
+        end
       end
 
       return "To: #{to}
@@ -267,7 +233,7 @@ module URI
 "
     end
     alias to_rfc822text to_mailtext
-  end # MailTo
+  end
 
   @@schemes['MAILTO'] = MailTo
-end # URI
+end