* lib/net/http.rb: update document.

* lib/net/pop.rb: ditto.
* lib/net/protocol.rb: ditto.


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

4 files changed, 88 insertions, 69 deletions

diff --git a/ChangeLog b/ChangeLog
index 3c26ca8ab6..a2b919c4db 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+Wed Aug  6 01:18:50 2003  Minero Aoki  <aamine@loveruby.net>
+
+	* lib/net/http.rb: update document.
+
+	* lib/net/pop.rb: ditto.
+
+	* lib/net/protocol.rb: ditto.
+
 Tue Aug  5 17:58:57 2003  WATANABE Hirofumi  <eban@ruby-lang.org>
 
 	* lib/fileutils.rb (install): should preserve timestamp only.
diff --git a/lib/net/http.rb b/lib/net/http.rb
index 908ba72e6c..33f1863bbd 100644
--- a/lib/net/http.rb
+++ b/lib/net/http.rb
@@ -308,7 +308,7 @@ module Net
       80
     end
 
-    def HTTP.socket_type   #:nodoc:
+    def HTTP.socket_type   #:nodoc: obsolete
       InternetMessageIO
     end
 
@@ -358,8 +358,17 @@ module Net
       "#<#{self.class} #{@address}:#{@port} open=#{started?}>"
     end
 
-    def set_debug_output( arg )   # :nodoc:
-      @debug_output = arg
+    # *WARNING* This method causes serious security hole.
+    # Never use this method in product code.
+    #
+    # Set an output stream for debugging.
+    #
+    #   http = Net::HTTP.new
+    #   http.set_debug_output $stderr
+    #   http.start { .... }
+    #
+    def set_debug_output( output )
+      @debug_output = output
     end
 
     # The host name to connect to.
@@ -389,7 +398,7 @@ module Net
       @started
     end
 
-    alias active? started?   #:nodoc:
+    alias active? started?   #:nodoc: obsolete
 
     attr_accessor :close_on_empty_response
 
@@ -521,8 +530,8 @@ module Net
       self.class.proxy_pass
     end
 
-    alias proxyaddr proxy_address   #:nodoc:
-    alias proxyport proxy_port      #:nodoc:
+    alias proxyaddr proxy_address   #:nodoc: obsolete
+    alias proxyport proxy_port      #:nodoc: obsolete
 
     private
 
@@ -540,7 +549,7 @@ module Net
       path
     end
 
-    module ProxyDelta   #:nodoc:
+    module ProxyDelta   #:nodoc: internal use only
       private
 
       # with proxy
@@ -687,7 +696,7 @@ module Net
       res
     end
 
-    def put( path, data, initheader = nil ) #:nodoc:
+    def put( path, data, initheader = nil )   #:nodoc:
       res = request(Put.new(path, initheader), data)
       @newimpl or res.value
       res
@@ -769,10 +778,10 @@ module Net
       request Put.new(path, initheader), data, &block
     end
 
-    alias get2   request_get    #:nodoc:
-    alias head2  request_head   #:nodoc:
-    alias post2  request_post   #:nodoc:
-    alias put2   request_put    #:nodoc:
+    alias get2   request_get    #:nodoc: obsolete
+    alias head2  request_head   #:nodoc: obsolete
+    alias post2  request_post   #:nodoc: obsolete
+    alias put2   request_put    #:nodoc: obsolete
 
 
     # Sends an HTTP request to the HTTP server.
@@ -904,11 +913,11 @@ module Net
   #
   module HTTPHeader
 
-    def size   #:nodoc:
+    def size   #:nodoc: obsolete
       @header.size
     end
 
-    alias length size   #:nodoc:
+    alias length size   #:nodoc: obsolete
 
     # Returns the header field corresponding to the case-insensitive key.
     # For example, a key of "Content-Type" might return "text/html"
@@ -1122,8 +1131,7 @@ module Net
     # write
     #
 
-    # internal use only
-    def exec( sock, ver, path, body )   #:nodoc:
+    def exec( sock, ver, path, body )   #:nodoc: internal use only
       if body
         check_body_permitted
         send_request_with_body sock, ver, path, body
@@ -1221,7 +1229,7 @@ module Net
       @response = res
     end
     attr_reader :response
-    alias data response
+    alias data response    #:nodoc: obsolete
   end
   class HTTPError < ProtocolError
     include HTTPExceptions
@@ -1306,7 +1314,7 @@ module Net
       self::HAS_BODY
     end
 
-    def HTTPResponse.exception_type   # :nodoc:
+    def HTTPResponse.exception_type   # :nodoc: internal use only
       self::EXCEPTION_TYPE
     end
   end   # redefined after
@@ -1524,7 +1532,7 @@ module Net
 
     class << self
 
-      def read_new( sock )   #:nodoc:
+      def read_new( sock )   #:nodoc: internal use only
         httpv, code, msg = read_status_line(sock)
         res = response_class(code).new(httpv, code, msg)
         each_response_header(sock) do |k,v|
@@ -1571,7 +1579,7 @@ module Net
 
     include HTTPHeader
 
-    def initialize( httpv, code, msg )   #:nodoc:
+    def initialize( httpv, code, msg )   #:nodoc: internal use only
       @http_version = httpv
       @code         = code
       @message      = msg
@@ -1591,7 +1599,7 @@ module Net
 
     # HTTP result message. For example, 'Not Found'.
     attr_reader :message
-    alias msg message   # :nodoc:
+    alias msg message   # :nodoc: obsolete
 
     def inspect
       "#<#{self.class} #{@code} readbody=#{@read}>"
@@ -1623,7 +1631,8 @@ module Net
       self.class::EXCEPTION_TYPE
     end
 
-    def value   #:nodoc:
+    # Raises HTTP error if the response is not 2xx.
+    def value
       error! unless HTTPSuccess === self
     end
 
@@ -1642,7 +1651,7 @@ module Net
     # body
     #
 
-    def reading_body( sock, reqmethodallowbody )  #:nodoc:
+    def reading_body( sock, reqmethodallowbody )  #:nodoc: internal use only
       @socket = sock
       @body_exist = reqmethodallowbody && self.class.body_permitted?
       begin
@@ -1712,7 +1721,7 @@ module Net
       read_body()
     end
 
-    alias entity body   #:nodoc:
+    alias entity body   #:nodoc: obsolete
 
     private
 
@@ -1774,7 +1783,7 @@ module Net
   class HTTP
     ProxyMod = ProxyDelta
   end
-  module NetPrivate #:nodoc:
+  module NetPrivate   #:nodoc:
     HTTPRequest = ::Net::HTTPRequest
   end
 
diff --git a/lib/net/pop.rb b/lib/net/pop.rb
index 5b4ad69c73..2d4b57162e 100644
--- a/lib/net/pop.rb
+++ b/lib/net/pop.rb
@@ -165,13 +165,14 @@
 # The POPMail#unique_id() method returns the unique-id of the message as a
 # String. Normally the unique-id is a hash of the message.
 # 
+
 require 'net/protocol'
 require 'digest/md5'
 
 module Net
 
-  # Non-authentication POP3 protocol error (reply code "-ERR", except
-  # authentication.
+  # Non-authentication POP3 protocol error
+  # (reply code "-ERR", except authentication).
   class POPError < ProtocolError; end
 
   # POP3 authentication error.
@@ -199,8 +200,7 @@ module Net
       110
     end
 
-    # obsolete
-    def POP3.socket_type # :nodoc:
+    def POP3.socket_type   #:nodoc: obsolete
       Net::InternetMessageIO
     end
 
@@ -218,6 +218,7 @@ module Net
     #     Net::POP3::APOP($is_apop).start(addr, port) {|pop|
     #       ....
     #     }
+    #
     def POP3.APOP( isapop )
       isapop ? APOP : POP3
     end
@@ -240,6 +241,7 @@ module Net
     #       file.write m.pop
     #       m.delete if $DELETE
     #     end
+    #
     def POP3.foreach( address, port = nil,
                       account = nil, password = nil,
                       isapop = false, &block )  # :yields: message
@@ -259,6 +261,7 @@ module Net
     #                          'YourAccount', 'YourPassword') do |m|
     #       file.write m.pop
     #     end
+    #
     def POP3.delete_all( address, port = nil,
                          account = nil, password = nil,
                          isapop = false, &block )
@@ -278,6 +281,7 @@ module Net
     #     # Example 2: APOP
     #     Net::POP3.auth_only('pop.example.com', 110,
     #                         'YourAccount', 'YourPassword', true)
+    #
     def POP3.auth_only( address, port = nil,
                         account = nil, password = nil,
                         isapop = false )
@@ -363,6 +367,7 @@ module Net
     #   pop.start(account, passwd) {
     #     ....
     #   }
+    #
     def set_debug_output( arg )
       @debug_output = arg
     end
@@ -394,7 +399,7 @@ module Net
       @started
     end
 
-    alias active? started?   # obsolete
+    alias active? started?   #:nodoc: obsolete
 
     # Starts a POP3 session.
     #
@@ -540,8 +545,7 @@ module Net
       end
     end
 
-    # internal use only (called from POPMail#uidl).
-    def set_all_uids
+    def set_all_uids   #:nodoc: internal use only (called from POPMail#uidl)
       command().uidl.each do |num, uid|
         @mails.find {|m| m.number == num }.uid = uid
       end
@@ -554,23 +558,27 @@ module Net
   POPSession  = POP3
   POP3Session = POP3
 
+  #
   # This class is equivalent to POP3, except that it uses APOP authentication.
+  #
   class APOP < POP3
-
     # Always returns true.
     def apop?
       true
     end
   end
 
+  # class aliases
   APOPSession = APOP
 
+  #
   # This class represents a message which exists on the POP server.
   # Instances of this class are created by the POP3 class; they should
   # not be directly created by the user.
+  #
   class POPMail
 
-    def initialize( num, len, pop, cmd ) # :nodoc:
+    def initialize( num, len, pop, cmd )   #:nodoc:
       @number = num
       @length = len
       @pop = pop
@@ -637,8 +645,8 @@ module Net
       end
     end
 
-    alias all pop    # backward compatibility
-    alias mail pop   # backward compatibility
+    alias all pop    #:nodoc: obsolete
+    alias mail pop   #:nodoc: obsolete
 
     # Fetches the message header and +lines+ lines of body. 
     # The optional +dest+ argument is obsolete.
@@ -677,12 +685,13 @@ module Net
     #         n += 1
     #       end
     #     }
+    #
     def delete
       @command.dele @number
       @deleted = true
     end
 
-    alias delete! delete    # backward compatibility
+    alias delete! delete    #:nodoc: obsolete
 
     # True if the mail has been deleted.
     def deleted?
@@ -701,15 +710,14 @@ module Net
 
     alias uidl unique_id
 
-    # internal use only (used from POP3#set_all_uids).
-    def uid=( uid )
+    def uid=( uid )   #:nodoc: internal use only (used from POP3#set_all_uids)
       @uid = uid
     end
 
   end   # class POPMail
 
 
-  class POP3Command # :nodoc:
+  class POP3Command   #:nodoc: internal use only
 
     def initialize( sock )
       @socket = sock
@@ -718,7 +726,6 @@ module Net
       @apop_stamp = res.slice(/<.+>/)
     end
 
-    # Provide human-readable stringification of class state.
     def inspect
       "#<#{self.class} socket=#{@socket}>"
     end
diff --git a/lib/net/protocol.rb b/lib/net/protocol.rb
index d33e93b266..eb1284735f 100644
--- a/lib/net/protocol.rb
+++ b/lib/net/protocol.rb
@@ -1,30 +1,29 @@
-=begin
-
-= net/protocol.rb
-
-Copyright (c) 1999-2003 Yukihiro Matsumoto
-Copyright (c) 1999-2003 Minero Aoki
-
-written and maintained by Minero Aoki <aamine@loveruby.net>
-
-This program is free software. You can re-distribute and/or
-modify this program under the same terms as Ruby itself,
-Ruby Distribute License or GNU General Public License.
-
-$Id$
-
-WARNING: This file is going to remove.
-Do not rely on the implementation written in this file.
-
-=end
+#
+# = net/protocol.rb
+#
+#--
+# Copyright (c) 1999-2003 Yukihiro Matsumoto
+# Copyright (c) 1999-2003 Minero Aoki
+#
+# written and maintained by Minero Aoki <aamine@loveruby.net>
+#
+# This program is free software. You can re-distribute and/or
+# modify this program under the same terms as Ruby itself,
+# Ruby Distribute License or GNU General Public License.
+#
+# $Id$
+#++
+#
+# WARNING: This file is going to remove.
+# Do not rely on the implementation written in this file.
+#
 
 require 'socket'
 require 'timeout'
 
-
 module Net
 
-  class Protocol
+  class Protocol   #:nodoc: internal use only
     private
     def Protocol.protocol_param( name, val )
       module_eval(<<-End, __FILE__, __LINE__ + 1)
@@ -46,7 +45,7 @@ module Net
   ProtocRetryError = ProtoRetriableError
 
 
-  class InternetMessageIO
+  class InternetMessageIO   #:nodoc: internal use only
 
     class << self
       alias open new
@@ -415,10 +414,7 @@ module Net
   end
 
 
-  #
-  # The reader adapter class for internal use only.
-  #
-  class ReadAdapter
+  class ReadAdapter   #:nodoc: internal use only
 
     def initialize( block )
       @block = block
@@ -446,8 +442,7 @@ module Net
   end
 
 
-  # For backward compatibility
-  module NetPrivate
+  module NetPrivate   #:nodoc: obsolete
     Socket = ::Net::InternetMessageIO
   end