o protocol.rb, http.rb, smtp.rb, pop.rb: update RD documents

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

lib/net/http.rb

@@ -23,18 +23,28 @@ module Net
 
 == Class Methods
 
-: new( address, port = 80 )
+: new( address = 'localhost', port = 80 )
-  create new HTTP object.
+  creates a new Net::HTTP object.
+
+: start( address = 'localhost', port = 80 )
+: start( address = 'localhost', port = 80 ) {|http| .... }
+  equals to Net::HTTP.new( address, port ).start
 
 : port
-  returns HTTP default port, 80
+  HTTP default port, 80
 
 : command_type
-  returns Command class, HTTPCommand
+  Command class for Net::HTTP, HTTPCommand
-
 
 == Methods
 
+: start
+: start {|http| .... }
+  creates a new Net::HTTP object and starts HTTP session.
+
+  When this method is called as iterator, gives HTTP object to block
+  and close HTTP session after block call finished.
+
 : get( path, header = nil, dest = '' )
 : get( path, header = nil ) {|str| .... }
   get data from "path" on connecting host.

lib/net/pop.rb

@@ -28,21 +28,28 @@ Net::Protocol
 === Class Methods
 
 : new( address = 'localhost', port = 110 )
-  This method create a new POP3 object.
+  creates a new Net::POP3 object.
-  This will not open connection yet.
+  This method does not open TCP connection yet.
 
+: start( address = 'localhost', port = 110, *protoargs )
+: start( address = 'localhost', port = 110, *protoargs ) {|pop| .... }
+  equals to Net::POP3.new( address, port ).start( *protoargs )
 
 === Methods
 
 : start( account, password )
-  This method start POP3.
+: start( account, password ) {|pop| .... }
+  starts POP3 session.
 
-: each{|popmail| ...}
+  When called as iterator, give a POP3 object to block and
+  close session after block call is finished.
+
+: each {|popmail| .... }
   This method is equals to "pop3.mails.each"
 
 : mails
-  This method returns an array of ((URL:#POPMail)).
+  an array of ((URL:#POPMail)).
-  This array is renewed when login.
+  This array is renewed when session started.
 
 =end
 

lib/net/protocol.rb

@@ -30,17 +30,15 @@ Object
 : new( address = 'localhost', port = nil )
   This method Creates a new protocol object.
 
-: start( address = 'localhost', port = nil, *args )
+: start( address = 'localhost', port = nil, *protoargs )
-: start( address = 'localhost', port = nil, *args ){|proto| .... }
+: start( address = 'localhost', port = nil, *protoargs ) {|proto| .... }
-  This method creates a new Protocol object and start session.
+  This method creates a new Protocol object and opens a session.
-  If you call this method with block, Protocol object give itself
+  equals to Net::Protocol.new( address, port ).start( *protoargs )
-  to block and finish session when block returns.
 
 : Proxy( address, port )
   This method creates a proxy class of its protocol.
   Arguments are address/port of proxy host.
 
-
 === Methods
 
 : address
@@ -50,11 +48,15 @@ Object
   connecting port number
 
 : start( *args )
-  This method start protocol. If you call this method when the protocol
+: start( *args ) {|proto| .... }
-  is already started, this only returns false without doing anything.
+  This method starts protocol. If protocol was already started,
+  do nothing and returns false.
 
   '*args' are specified in subclasses.
 
+  When is called as iterator, gives Protocol object to block and
+  close session when block finished.
+
 : finish
   This method ends protocol. If you call this method before protocol starts,
   it only return false without doing anything.

lib/net/smtp.rb

@@ -28,15 +28,24 @@ Net::Protocol
 === Class Methods
 
 : new( address = 'localhost', port = 25 )
-  This method create new SMTP object.
+  creates a new Net::SMTP object.
 
+: start( address = 'localhost', port = 25, *protoargs )
+: start( address = 'localhost', port = 25, *protoargs ) {|smtp| .... }
+  same to Net::SMTP.new( address, port ).start( *protoargs )
 
 === Methods
 
-: start( helo_domain = ENV['HOSTNAME'] || ENV['HOST'], account = nil, password = nil, authtype = nil )
+: start( helo_domain = Socket.gethostname, \
-  This method opens TCP connection and start SMTP.
+         account = nil, password = nil, authtype = nil )
+: start( helo_domain = Socket.gethostname, \
+         account = nil, password = nil, authtype = nil ) {|smtp| .... }
+  opens TCP connection and starts SMTP session.
   If protocol had been started, do nothing and return false.
 
+  When this methods is called as iterator, give a SMTP object to block and
+  close session after block call finished.
+
   If account and password are given, is trying to get authentication
   by using AUTH command. "authtype" is :plain (symbol) or :cram_md5.