Land rapid7#5059, @void-in's documentation clean up

Author: jvazquez-r7

lib/metasploit/framework/credential_collection.rb

@@ -79,7 +79,7 @@ def initialize(opts = {})
   # Adds a string as an addition private credential
   # to be combined in the collection.
   #
-  # @param [String] :private_str the string to use as a private
+  # @param [String] private_str the string to use as a private
   # @return [void]
   def add_private(private_str='')
     additional_privates << private_str
@@ -88,7 +88,7 @@ def add_private(private_str='')
   # Adds a string as an addition public credential
   # to be combined in the collection.
   #
-  # @param [String] :public_str the string to use as a public
+  # @param [String] public_str the string to use as a public
   # @return [void]
   def add_public(public_str='')
     additional_publics << public_str

lib/metasploit/framework/login_scanner/http.rb

@@ -189,13 +189,13 @@ def check_setup
 
         # Sends a HTTP request with Rex
         #
-        # @param [Hash] Native support includes the following (also see Rex::Proto::Http::Request#request_cgi)
-        # @option opts[String] 'host' The remote host
-        # @option opts[Fixnum] 'port' The remote port
-        # @option opts[Boolean] 'ssl' The SSL setting, TrueClass or FalseClass
-        # @option opts[String]  'proxies' The proxies setting
-        # @option opts[Credential] 'credential' A credential object
-        # @option opts['Hash'] 'context' A context
+        # @param [Hash] opts native support includes the following (also see Rex::Proto::Http::Request#request_cgi)
+        # @option opts [String] 'host' The remote host
+        # @option opts [Fixnum] 'port' The remote port
+        # @option opts [Boolean] 'ssl' The SSL setting, TrueClass or FalseClass
+        # @option opts [String]  'proxies' The proxies setting
+        # @option opts [Credential] 'credential' A credential object
+        # @option opts ['Hash'] 'context' A context
         # @raise [Rex::ConnectionError] One of these errors has occured: EOFError, Errno::ETIMEDOUT, Rex::ConnectionError, ::Timeout::Error
         # @return [Rex::Proto::Http::Response] The HTTP response
         # @return [NilClass] An error has occured while reading the response (see #Rex::Proto::Http::Client#read_response)
@@ -356,7 +356,7 @@ def set_sane_defaults
 
         # Combine the base URI with the target URI in a sane fashion
         #
-        # @param [String] The target URL
+        # @param [String] target_uri the target URL
         # @return [String] the final URL mapped against the base
         def normalize_uri(target_uri)
           (self.uri.to_s + "/" + target_uri.to_s).gsub(/\/+/, '/')

lib/metasploit/framework/login_scanner/symantec_web_gateway.rb

@@ -29,7 +29,7 @@ def check_setup
 
         # Returns the latest sid from Symantec Web Gateway.
         #
-        # @returns [String] The PHP Session ID for Symantec Web Gateway login
+        # @return [String] The PHP Session ID for Symantec Web Gateway login
         def get_last_sid
           @last_sid ||= lambda {
             # We don't have a session ID. Well, let's grab one right quick from the login page.

lib/msf/core/auxiliary/auth_brute.rb

@@ -108,9 +108,9 @@ def prepend_db_hashes(cred_collection)
   # This method takes a {Metasploit::Framework::CredentialCollection} and prepends existing SSHKeys
   # from the database. This allows the users to use the DB_ALL_CREDS option.
   #
-  # @param cred_collection [Metasploit::Framework::CredentialCollection]
+  # @param [Metasploit::Framework::CredentialCollection] cred_collection
   #    the credential collection to add to
-  # @return [Metasploit::Framework::CredentialCollection] the modified Credentialcollection
+  # @return [Metasploit::Framework::CredentialCollection] cred_collection the modified Credentialcollection
   def prepend_db_keys(cred_collection)
     if prepend_db_creds?
       each_ssh_cred do |cred|
@@ -140,8 +140,8 @@ def prepend_db_passwords(cred_collection)
   # {Metasploit::Framework::CredentialCollection} as dictated by the
   # selected datastore options.
   #
-  # @param [Metasploit::Framework::CredentialCollection] the credential collection to add to
-  # @param [Metasploit::Credential::Core] the Credential Core to process
+  # @param [Metasploit::Framework::CredentialCollection] cred_collection the credential collection to add to
+  # @param [Metasploit::Credential::Core] cred the credential to process
   def process_cred_for_collection(cred_collection, cred)
     msf_cred = cred.to_credential
     cred_collection.prepend_cred(msf_cred) if datastore['DB_ALL_CREDS']

lib/msf/core/auxiliary/jtr.rb

@@ -77,7 +77,7 @@ def new_john_cracker
   end
 
   # This method instantiates a {Metasploit::Framework::JtR::Wordlist}, writes the data
-  # out to a file and returns the {rex::quickfile} object.
+  # out to a file and returns the {Rex::Quickfile} object.
   #
   # @return [nilClass] if there is no active framework db connection
   # @return [Rex::Quickfile] if it successfully wrote the wordlist to a file

lib/msf/core/auxiliary/report.rb

@@ -113,13 +113,11 @@ def get_host(opts)
 
   #
   # Report a client connection
-  #
-  # opts must contain
-  #	:host      the address of the client connecting
-  #	:ua_string a string that uniquely identifies this client
-  # opts can contain
-  #	:ua_name a brief identifier for the client, e.g. "Firefox"
-  #	:ua_ver  the version number of the client, e.g. "3.0.11"
+  # @param opts [Hash] report client information based on user-agent
+  # @option opts [String] :host the address of the client connecting
+  # @option opts [String] :ua_string a string that uniquely identifies this client
+  # @option opts [String] :ua_name a brief identifier for the client, e.g. "Firefox"
+  # @option opts [String] :ua_ver  the version number of the client, e.g. "3.0.11"
   #
   def report_client(opts={})
     return if not db
@@ -161,7 +159,7 @@ def report_note(opts={})
   # by a module. This method is deprecated and the new Metasploit::Credential methods
   # should be used directly instead.
   #
-  # @param :opts [Hash] the option hash
+  # @param opts [Hash] the option hash
   # @option opts [String] :host the address of the host (also takes a {Mdm::Host})
   # @option opts [Fixnum] :port the port of the connected service
   # @option opts [Mdm::Service] :service an optional Service object to build the cred for

lib/msf/core/exploit/smb/client/psexec.rb

@@ -35,7 +35,7 @@ def initialize(info = {})
   # Retrieve the SERVICE_NAME option, generate a random
   # one if not already set.
   #
-  # @return service_name [String] the name of the service.
+  # @return [String] service_name the name of the service.
   def service_name
     @service_name ||= datastore['SERVICE_NAME']
     @service_name ||= Rex::Text.rand_text_alpha(8)
@@ -44,15 +44,15 @@ def service_name
   # Retrieve the SERVICE_DISPLAY_NAME option, generate a random
   # one if not already set.
   #
-  # @return service_display_name [String] the display name of the service.
+  # @return [String] the display name of the service.
   def display_name
     @display_name ||= datastore['SERVICE_DISPLAY_NAME']
     @display_name ||= Rex::Text.rand_text_alpha(16)
   end
 
   # Retrieve the SERVICE_DESCRIPTION option
   #
-  # @return service_description [String] the service description.
+  # @return [String] the service description.
   def service_description
     @service_description ||= datastore['SERVICE_DESCRIPTION']
   end

lib/msf/core/post/windows/mssql.rb

@@ -54,9 +54,9 @@ def check_for_sqlserver(instance = nil)
         end
 
         # Identifies a valid SQL Server command line client on the host and sets
-        # @sql_client
+        # sql_client
         #
-        # @see #sql_client
+        # @see sql_client
         # @return [String, nil] the SQL command line client
         def get_sql_client
           client = nil

lib/msf/core/post/windows/services.rb

@@ -528,7 +528,7 @@ def service_restart(name, start_type=START_TYPE_AUTO, server=nil)
   # Parses out a SERVICE_STATUS struct from the
   # lpServiceStatus out parameter
   #
-  # @param (lpServiceStatus)
+  # @param lpServiceStatus [String] the latest status of calling service
   #
   # @return [Hash] Containing SERVICE_STATUS values
   #

lib/msf/http/jboss/base.rb

@@ -49,7 +49,7 @@ def http_verb
 
   # Try to auto detect the target architecture and platform
   #
-  # @param [Array] The available targets
+  # @param [Array] available_targets The available targets
   # @return [Msf::Module::Target, nil] The detected target or nil
   def auto_target(available_targets)
     if http_verb == 'HEAD'