more docs for Connection::Term. Docs for the connection proxy implementations.

5 files changed, 101 insertions, 27 deletions

diff --git a/lib/net/ssh/connection/term.rb b/lib/net/ssh/connection/term.rb
index d9752f7..3e1caa5 100644
--- a/lib/net/ssh/connection/term.rb
+++ b/lib/net/ssh/connection/term.rb
@@ -1,6 +1,9 @@
 module Net; module SSH; module Connection
       
-  # Terminal opcodes, for use when opening pty's.
+  # These constants are used when requesting a pseudo-terminal (via
+  # Net::SSH::Connection::Channel#request_pty). The descriptions for each are
+  # taken directly from RFC 4254 ("The Secure Shell (SSH) Connection Protocol"),
+  # http://tools.ietf.org/html/rfc4254.
   module Term
     # Interrupt character; 255 if none. Similarly for the other characters.
     # Not all of these characters are supported on all systems.
diff --git a/lib/net/ssh/proxy/errors.rb b/lib/net/ssh/proxy/errors.rb
index 1343919..6eb3501 100644
--- a/lib/net/ssh/proxy/errors.rb
+++ b/lib/net/ssh/proxy/errors.rb
@@ -8,7 +8,7 @@ module Net; module SSH; module Proxy
   # Used for reporting proxy connection errors.
   class ConnectError < Error; end
 
-  # Used when the server doesn't recognize the users credentials
+  # Used when the server doesn't recognize the user's credentials.
   class UnauthorizedError < Error; end
 
 end; end; end
diff --git a/lib/net/ssh/proxy/http.rb b/lib/net/ssh/proxy/http.rb
index abf3c7e..4f86dcf 100644
--- a/lib/net/ssh/proxy/http.rb
+++ b/lib/net/ssh/proxy/http.rb
@@ -3,18 +3,43 @@ require 'net/ssh/proxy/errors'
 
 module Net; module SSH; module Proxy
 
-  # An implementation of a socket factory that returns a socket which
-  # will tunnel the connection through an HTTP proxy. It allows explicit
-  # specification of the user and password, but if none are given it
-  # will look in the HTTP_PROXY_USER/HTTP_PROXY_PASSWORD and
-  # CONNECT_USER/CONNECT_PASSWORD environment variables as well.
+  # An implementation of an HTTP proxy. To use it, instantiate it, then
+  # pass the instantiated object via the :proxy key to Net::SSH.start:
+  #
+  #   require 'net/ssh/proxy/http'
+  #
+  #   proxy = Net::SSH::Proxy::HTTP.new('proxy.host', proxy_port)
+  #   Net::SSH.start('host', 'user', :proxy => proxy) do |ssh|
+  #     ...
+  #   end
+  #
+  # If the proxy requires authentication, you can pass :user and :password
+  # to the proxy's constructor:
+  #
+  #   proxy = Net::SSH::Proxy::HTTP.new('proxy.host', proxy_port,
+  #      :user => "user", :password => "password")
+  #
+  # Note that HTTP digest authentication is not supported; Basic only at
+  # this point.
   class HTTP
 
-    attr_reader :proxy_host, :proxy_port
+    # The hostname or IP address of the HTTP proxy.
+    attr_reader :proxy_host
+
+    # The port number of the proxy.
+    attr_reader :proxy_port
+
+    # The map of additional options that were given to the object at
+    # initialization.
     attr_reader :options
 
     # Create a new socket factory that tunnels via the given host and
-    # port.
+    # port. The +options+ parameter is a hash of additional settings that
+    # can be used to tweak this proxy connection. Specifically, the following
+    # options are supported:
+    #
+    # * :user => the user name to use when authenticating to the proxy
+    # * :password => the password to use when authenticating
     def initialize(proxy_host, proxy_port=80, options={})
       @proxy_host = proxy_host
       @proxy_port = proxy_port
diff --git a/lib/net/ssh/proxy/socks4.rb b/lib/net/ssh/proxy/socks4.rb
index 76d946a..fdb1e32 100644
--- a/lib/net/ssh/proxy/socks4.rb
+++ b/lib/net/ssh/proxy/socks4.rb
@@ -7,20 +7,37 @@ module Net
   module SSH
     module Proxy
 
-      # An implementation of a socket factory that returns a socket which
-      # will tunnel the connection through a SOCKS4 proxy. It allows explicit
-      # specification of the user.
+      # An implementation of a SOCKS4 proxy. To use it, instantiate it, then
+      # pass the instantiated object via the :proxy key to Net::SSH.start:
+      #
+      #   require 'net/ssh/proxy/socks4'
+      #
+      #   proxy = Net::SSH::Proxy::SOCKS4.new('proxy.host', proxy_port, :user => 'user')
+      #   Net::SSH.start('host', 'user', :proxy => proxy) do |ssh|
+      #     ...
+      #   end
       class SOCKS4
 
+        # The SOCKS protocol version used by this class
         VERSION = 4
+
+        # The packet type for connection requests
         CONNECT = 1
+
+        # The status code for a successful connection
         GRANTED = 90
 
-        attr_reader :proxy_host, :proxy_port
+        # The proxy's host name or IP address, as given to the constructor.
+        attr_reader :proxy_host
+
+        # The proxy's port number.
+        attr_reader :proxy_port
+
+        # The additional options that were given to the proxy's constructor.
         attr_reader :options
 
         # Create a new proxy connection to the given proxy host and port.
-        # Optionally, a @:user@ option may be given to identify the username
+        # Optionally, a :user key may be given to identify the username
         # with which to authenticate.
         def initialize(proxy_host, proxy_port=1080, options={})
           @proxy_host = proxy_host
diff --git a/lib/net/ssh/proxy/socks5.rb b/lib/net/ssh/proxy/socks5.rb
index b6c5fd9..fa2862f 100644
--- a/lib/net/ssh/proxy/socks5.rb
+++ b/lib/net/ssh/proxy/socks5.rb
@@ -5,24 +5,53 @@ module Net
   module SSH
     module Proxy
 
-      # An implementation of a socket factory that returns a socket which
-      # will tunnel the connection through a SOCKS5 proxy. It allows explicit
-      # specification of the user and password.
+      # An implementation of a SOCKS5 proxy. To use it, instantiate it, then
+      # pass the instantiated object via the :proxy key to Net::SSH.start:
+      #
+      #   require 'net/ssh/proxy/socks5'
+      #
+      #   proxy = Net::SSH::Proxy::SOCKS5.new('proxy.host', proxy_port,
+      #     :user => 'user', :password => "password")
+      #   Net::SSH.start('host', 'user', :proxy => proxy) do |ssh|
+      #     ...
+      #   end
       class SOCKS5
-        VERSION        = 5
+        # The SOCKS protocol version used by this class
+        VERSION = 5
+
+        # The SOCKS authentication type for requests without authentication
         METHOD_NO_AUTH = 0
-        METHOD_PASSWD  = 2
-        METHOD_NONE    = 0xFF
-        CMD_CONNECT    = 1
-        ATYP_IPV4      = 1
-        ATYP_DOMAIN    = 3
-        SUCCESS        = 0
-
-        attr_reader :proxy_host, :proxy_port
+
+        # The SOCKS authentication type for requests via username/password
+        METHOD_PASSWD = 2
+
+        # The SOCKS authentication type for when there are no supported
+        # authentication methods.
+        METHOD_NONE = 0xFF
+
+        # The SOCKS packet type for requesting a proxy connection.
+        CMD_CONNECT = 1
+
+        # The SOCKS address type for connections via IP address.
+        ATYP_IPV4 = 1
+
+        # The SOCKS address type for connections via domain name.
+        ATYP_DOMAIN = 3
+
+        # The SOCKS response code for a successful operation.
+        SUCCESS = 0
+
+        # The proxy's host name or IP address
+        attr_reader :proxy_host
+
+        # The proxy's port number
+        attr_reader :proxy_port
+
+        # The map of options given at initialization
         attr_reader :options
 
         # Create a new proxy connection to the given proxy host and port.
-        # Optionally, @:user@ and @:password@ options may be given to
+        # Optionally, :user and :password options may be given to
         # identify the username and password with which to authenticate.
         def initialize(proxy_host, proxy_port=1080, options={})
           @proxy_host = proxy_host