net.rb in ronin-0.3.0

- old
+ new

@@ -1,9 +1,7 @@
 #
-#--
-# Ronin - A Ruby platform designed for information security and data
-# exploration tasks.
+# Ronin - A Ruby platform for exploit development and security research.
 #
 # Copyright (c) 2006-2009 Hal Brodigan (postmodern.mod3 at gmail.com)
 #
 # This program is free software; you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -16,40 +14,58 @@
 # GNU General Public License for more details.
 #
 # You should have received a copy of the GNU General Public License
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
-#++
 #
 
 require 'ronin/network/smtp/email'
 
 require 'net/smtp'
 
 module Net
   #
-  # See <tt>Ronin::Network::SMTP.message</tt>.
+  # @see Ronin::Network::SMTP.message
   #
   def Net.smtp_message(options={},&block)
     Ronin::Network::SMTP.message(options,&block)
   end
 
   #
-  # Connects to the SMTP server on the specified _host_ with the given
-  # _options_. If a _block_ is given it will be passed the newly created
-  # <tt>Net::SMTP</tt> object.
+  # Creates a connection to the SMTP server.
   #
-  # _options_ may contain the following keys:
-  # <tt>:port</tt>:: The port to connect to, defaults to
-  #                  <tt>Ronin::Network::SMTP.default_port</tt>.
-  # <tt>:helo</tt>:: The HELO domain.
-  # <tt>:auth</tt>:: The type of authentication to use. Can be
-  #                  either <tt>:login</tt>, <tt>:plain</tt> or
-  #                  <tt>:cram_md5</tt>.
-  # <tt>:user</tt>:: The user name to authenticate with.
-  # <tt>:password</tt>:: The password to authenticate with.
+  # @param [String] host
+  #   The host to connect to.
   #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @option options [Integer] :port (Ronin::Network::SMTP.default_port)
+  #   The port to connect to.
+  #
+  # @option options [String] :helo
+  #   The HELO domain.
+  #
+  # @option options [Symbol] :auth
+  #   The type of authentication to use. Can be either +:login+, +:plain+,
+  #   or +:cram_md5+.
+  #
+  # @option options [String] :user
+  #   The user-name to authenticate with.
+  #
+  # @option options [String] :password
+  #   The password to authenticate with.
+  #
+  # @yield [session]
+  #   If a block is given, it will be passed an SMTP session object.
+  #
+  # @yieldparam [Net::SMTP] session
+  #   The SMTP session.
+  #
+  # @return [Net::SMTP]
+  #   The SMTP session.
+  #
   def Net.smtp_connect(host,options={},&block)
     port = (options[:port] || Ronin::Network::SMTP.default_port)
 
     helo = options[:helo]
 
@@ -62,13 +78,25 @@
     block.call(sess) if block
     return sess
   end
 
   #
-  # Connects to the SMTP server on the specified _host_ with the given
-  # _options_. If a _block_ is given it will be passed the newly created
-  # <tt>Net::SMTP</tt> object. After the <tt>Net::SMTP</tt> object has been
-  # passed to the _block_ it will be closed.
+  # Starts a session with the SMTP server.
+  #
+  # @param [String] host
+  #   The host to connect to.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @yield [session]
+  #   If a block is given, it will be passed an SMTP session object.
+  #   After the block has returned, the session will be closed.
+  #
+  # @yieldparam [Net::SMTP] session
+  #   The SMTP session.
+  #
+  # @see Net.smtp_connect
   #
   def Net.smtp_session(host,options={},&block)
     Net.smtp_connect(host,options) do |sess|
       block.call(sess) if block
       sess.finish