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,61 +14,83 @@
 # 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/telnet'
 
 require 'net/telnet'
 
 module Net
   #
-  # Creates a new Telnet object with the specified _host_, given port
-  # and the given _options_. If a _block_ is given, it will be passed
-  # the newly created Telnet object.
+  # Creates a new Telnet connection.
   #
-  # _options_ may contain the following keys:
-  # <tt>:port</tt>:: The port to connect to. Defaults to
-  #                  <tt>Ronin::Network::Telnet.default_port</tt>, if not
-  #                  given.
-  # <tt>:binmode</tt>:: Indicates that newline substitution shall not
-  #                     be performed.
-  # <tt>:output_log</tt>:: The name of the file to write connection
-  #                        status messages and all received traffic to.
-  # <tt>:dump_log</tt>:: Similar to the <tt>:output_log</tt> option,
-  #                      but connection output is also written in
-  #                      hexdump format.
-  # <tt>:prompt</tt>:: A regular expression matching the host's
-  #                    command-line prompt sequence, used to determine
-  #                    when a command has finished. Defaults to
-  #                    <tt>Ronin::Network::Telnet.default_prompt</tt>, if
-  #                    not given.
-  # <tt>:telnet</tt>:: Indicates that the connection shall behave as a
-  #                    telnet connection. Defaults to +true+.
-  # <tt>:plain</tt>:: Indicates that the connection shall behave as a
-  #                   normal TCP connection.
-  # <tt>:timeout</tt>:: The number of seconds to wait before timing out
-  #                     both the initial attempt to connect to host,
-  #                     and all attempts to read data from the host.
-  #                     Defaults to
-  #                     <tt>Ronin::Network::Telnet.default_timeout</tt>,
-  #                     if not given.
-  # <tt>:wait_time</tt>:: The amount of time to wait after seeing what
-  #                       looks like a prompt.
-  # <tt>:proxy</tt>:: A proxy object to used instead of opening a
-  #                   direct connection to the host. Must be either
-  #                   another telnet object or an IO object.
-  #                   Defaults to
-  #                   <tt>Ronin::Network::Telnet.proxy</tt>, if not given.
-  # <tt>:user</tt>:: The user to login with.
-  # <tt>:password</tt>:: The password to login with.
+  # @param [String] host
+  #   The host to connect to.
   #
-  #   Telnet.connect('towel.blinkenlights.nl') # => Telnet
+  # @param [Hash] options
+  #   Additional options.
   #
+  # @option options [Integer] :port (Ronin::Network::Telnet.default_port)
+  #   The port to connect to.
+  #
+  # @option options [Boolean] :binmode
+  #   Indicates that newline substitution shall not be performed.
+  #
+  # @option options [String] :output_log
+  #   The name of the file to write connection status messages and all
+  #   received traffic to.
+  #
+  # @option options [String] :dump_log
+  #   Similar to the +:output_log+ option, but connection output is also
+  #   written in hexdump format.
+  #
+  # @option options [Regexp] :prompt (Ronin::Network::Telnet.default_prompt)
+  #   A regular expression matching the host command-line prompt sequence,
+  #   used to determine when a command has finished.
+  #
+  # @option options [Boolean] :telnet (true)
+  #   Indicates that the connection shall behave as a telnet connection.
+  #
+  # @option options [Boolean] :plain
+  #   Indicates that the connection shall behave as a normal TCP
+  #   connection.
+  #
+  # @option options [Integer] :timeout (Ronin::Network::Telnet.default_timeout)
+  #   The number of seconds to wait before timing out both the initial
+  #   attempt to connect to host, and all attempts to read data from the
+  #   host.
+  #
+  # @option options [Integer] :wait_time
+  #   The amount of time to wait after seeing what looks like a prompt.
+  #
+  # @option options [Net::Telnet, IO] :proxy (Ronin::Network::Telnet.proxy)
+  #   A proxy object to used instead of opening a direct connection to the
+  #   host.
+  #
+  # @option options [String] :user
+  #   The user to login as.
+  #
+  # @option options [String] :password
+  #   The password to login with.
+  #
+  # @yield [session]
+  #   If a block is given, it will be passed the newly created Telnet
+  #   session.
+  #
+  # @yieldparam [Net::Telnet] session
+  #   The newly created Telnet session.
+  #
+  # @return [Net::Telnet]
+  #   The Telnet session
+  #
+  # @example
+  #   Net.telnet_connect('towel.blinkenlights.nl')
+  #   # => #<Net::Telnet: ...>
+  #
   def Net.telnet_connect(host,options={},&block)
     sess_opts = {}
     sess_opts['Host'] = host
     sess_opts['Port'] = (options[:port] || Ronin::Network::Telnet.default_port)
     sess_opts['Binmode'] = options[:binmode]
@@ -95,19 +115,31 @@
     block.call(sess) if block
     return sess
   end
 
   #
-  # Creates a new Telnet object with the specified _host, given port
-  # and the given _options_. See telnet for a complete listing the
-  # _options_. If a _block_ is given, it will be passed the newly
-  # created Telnet object. After the telnet connection has been
-  # established, and the given _block_ has completed, the connection
-  # is then closed.
+  # Starts a new Telnet session.
   #
+  # @param [String] host
+  #   The host to connect to.
+  #
+  # @param [Hash] options
+  #   Additional options.
+  #
+  # @yield [session]
+  #   If a block is given, it will be passed the newly created
+  #   Telnet session. After the block has returned, the Telnet session
+  #   will be closed.
+  #
+  # @yieldparam [Net::Telnet] session
+  #   The newly created Telnet session.
+  #
+  # @example
   #   Net.telnet_session('towel.blinkenlights.nl') do |movie|
   #     movie.each_line { |line| puts line }
   #   end
+  #
+  # @see Net.telnet_session
   #
   def Net.telnet_session(host,options={},&block)
     Net.telnet_connect(host,options) do |sess|
       block.call(sess) if block
       sess.close