Final round of documentation

Author: wchen-r7

lib/msf/core/rpc/v10/client.rb

@@ -40,7 +40,8 @@ def initialize(info={})
   end
 
 
-  # Logs in by calling the 'auth.login' API.
+  # Logs in by calling the 'auth.login' API. The authentication token will expire 5 minutes
+  # after the last request was made.
   #
   # @param [String] user Username.
   # @param [String] pass Password.

lib/msf/core/rpc/v10/rpc_auth.rb

@@ -11,7 +11,8 @@ class RPC_Auth < RPC_Base
 rescue ::LoadError
 end
 
-  # Handles client authentication.
+  # Handles client authentication. The authentication token will expire 5 minutes after the
+  # last request was made.
   #
   # @param [String] user The username.
   # @param [String] pass The password.
@@ -79,7 +80,8 @@ def rpc_logout(token)
   end
 
 
-  # Returns a list of authentication tokens.
+  # Returns a list of authentication tokens including the temporary ones, permanent, or the ones
+  # stored in the backend.
   #
   # @return [Hash] A hash that contains a list of authentication tokens. It contains the following key:
   #  * 'tokens' [Array<string>] An array of tokens.
@@ -128,10 +130,10 @@ def rpc_token_add(token)
   end
 
 
-  # Generates a unique token, and automatically saved to the database.
+  # Generates a random 32-byte authentication token, and automatically saved to the database.
   #
   # @return [Hash] A hash indicating the action was successful, also the new token.
-  #                It contains the following keys:
+  #  It contains the following keys:
   #  * 'result' [String] The successful message: 'success'
   #  * 'token' [String] A new token.
   # @example Here's how you would use this from the client:
@@ -158,8 +160,10 @@ def rpc_token_generate
   end
 
 
-  # Removes a token from the database.
+  # Removes a token from the database. Similar to what #rpc_logout does internally, except this
+  # can remove tokens stored in the database backend (Mdm).
   #
+  # @see #rpc_logout
   # @param [String] token The token to delete.
   # @return [Hash] A hash indicating the action was successful. It contains the following key:
   #  * 'result' [String] The successful message: 'success'

lib/msf/core/rpc/v10/rpc_console.rb

@@ -15,7 +15,7 @@ def initialize(*args)
     @console_driver = Msf::Ui::Web::Driver.new(:framework => framework)
   end
 
-  # Creates a new framework console.
+  # Creates a new framework console instance.
   #
   # @param [Hash] opts See Msf::Ui::Web::Driver#create_console
   # @return [Hash] Information about the new console. It contains the following keys:
@@ -58,7 +58,7 @@ def rpc_list
   end
 
 
-  # Deletes a framework console.
+  # Deletes a framework console instance.
   #
   # @param [Fixnum] cid Framework console ID.
   # @return [Hash] A result indicating whether the action was successful or not.
@@ -74,7 +74,7 @@ def rpc_destroy(cid)
   end
 
 
-  # Returns the framework console output.
+  # Returns the framework console output in raw form.
   #
   # @param [Fixnum] cid Framework console ID.
   # @return [Hash] There are two different hashes you might get:
@@ -143,15 +143,12 @@ def rpc_tabs(cid, line)
   end
 
 
-  # Kills a framework session.
+  # Kills a framework session that serves the same purpose as [CTRL]+[C] to abort an interactive session.
+  # You might also want to considering using the session API calls instead of this.
   #
   # @param [Fixnum] cid Framework console ID.
-  # @return [Hash] There are two different hashes you might get:
-  #
-  #  If the console ID is invalid, you will get a hash like the following:
-  #  * 'result' [String] A value that says 'failure'.
-  #  If the console ID is valid, you will get the following that indicates the action was successful.
-  #  * 'result' [String] A value that says 'success'.
+  # @return [Hash] A hash indicating whether the action was successful or not. It contains:
+  #  * 'result' [String] A message that says 'success' if the console ID is valid (and successfully killed, otherwise 'failed')
   # @example Here's how you would use this from the client:
   #  rpc.call('console.session_kill', 4)
   def rpc_session_kill(cid)
@@ -162,15 +159,11 @@ def rpc_session_kill(cid)
   end
 
 
-  # Detaches a framework session.
+  # Detaches a framework session that serves the same purpos as [CTRL]+[Z] to background an interactive session.
   #
   # @param [Fixnum] cid Framework console ID.
-  # @return [Hash] There are two different hashes you might get:
-  #
-  #  If the console ID is invalid, you will get a hash like the following:
-  #  * 'result' [String] A value that says 'failure'.
-  #  If the console ID is valid, you will get the following that indicates the action was successful.
-  #  * 'result' [String] A value that says 'success'.
+  # @return [Hash] A hash indicating whether the action was successful or not. It contains:
+  #  * 'result' [String] A message that says 'success' if the console ID is valid (and successfully detached, otherwise 'failed')
   # @example Here's how you would use this from the client:
   #  rpc.call('console.session_detach', 4)
   def rpc_session_detach(cid)

lib/msf/core/rpc/v10/rpc_core.rb

@@ -98,7 +98,10 @@ def rpc_reload_modules
   end
 
 
-  # Adds a new module path.
+  # Adds a new local file system path (local to the server) as a module path. The module must be
+  # accessible to the user running the Metasploit service, and contain a top-level directory for
+  # each module type such as: exploits, nop, encoder, payloads, auxiliary, post. Also note that
+  # this will not unload modules that were deleted from the file system that were previously loaded.
   #
   # @param [String] path The new path to load.
   # @return [Hash] Module stats that contain the following keys: