Doc tag changes based on feedback.

.yardopts

@@ -2,7 +2,6 @@
 --exclude samples/
 --exclude \.ut\.rb/
 --exclude \.ts\.rb/
---no-private
 --files CONTRIBUTING.md,COPYING,HACKING,LICENSE
 lib/msf/**/*.rb
 lib/rex/**/*.rb

lib/msf/base/config.rb

@@ -11,6 +11,7 @@ class Config < Hash
   InstallRoot = File.expand_path(File.join(File.dirname(__FILE__), '..', '..', '..'))
 
   # Determines the base configuration directory.
+  #
   # @return [String] the base configuration directory
   def self.get_config_root
 
@@ -66,96 +67,112 @@ class Config < Hash
   ##
 
   # Returns the framework installation root.
+  #
   # @return [String] the framework installation root {InstallRoot}.
   def self.install_root
     InstallRoot
   end
 
   # Returns the configuration directory default.
+  #
   # @return [String] the root configuration directory.
   def self.config_directory
     self.new.config_directory
   end
 
   # Returns the global module directory.
+  #
   # @return [String] path to global module directory.
   def self.module_directory
     self.new.module_directory
   end
 
   # Returns the path that scripts can be loaded from.
+  #
   # @return [String] path to script directory.
   def self.script_directory
     self.new.script_directory
   end
 
   # Returns the directory that log files should be stored in.
+  #
   # @return [String] path to log directory.
   def self.log_directory
     self.new.log_directory
   end
 
   # Returns the directory that plugins are stored in.
+  #
   # @return [String] path to plugin directory.
   def self.plugin_directory
     self.new.plugin_directory
   end
 
   # Returns the user-specific plugin base path
+  #
   # @return [String] path to user-specific plugin directory.
   def self.user_plugin_directory
     self.new.user_plugin_directory
   end
 
   # Returns the directory in which session log files are to reside.
+  #
   # @return [String] path to session log directory.
   def self.session_log_directory
     self.new.session_log_directory
   end
 
   # Returns the directory in which captured data will reside.
+  #
   # @return [String] path to loot directory.
   def self.loot_directory
     self.new.loot_directory
   end
 
   # Returns the directory in which locally-generated data will reside.
+  #
   # @return [String] path to locally-generated data directory.
   def self.local_directory
     self.new.local_directory
   end
 
   # Returns the user-specific module base path
+  #
   # @return [String] path to user-specific modules directory.
   def self.user_module_directory
     self.new.user_module_directory
   end
 
   # Returns the user-specific script base path
+  #
   # @return [String] path to user-specific script directory.
   def self.user_script_directory
     self.new.user_script_directory
   end
 
   # Returns the data directory
+  #
   # @return [String] path to data directory.
   def self.data_directory
     self.new.data_directory
   end
 
   # Returns the full path to the configuration file.
+  #
   # @return [String] path to the configuration file.
   def self.config_file
     self.new.config_file
   end
 
   # Returns the full path to the history file.
+  #
   # @return [String] path the history file.
   def self.history_file
     self.new.history_file
   end
 
   # Initializes configuration, creating directories as necessary.
+  #
   # @return [void]
   def self.init
     self.new.init
@@ -163,7 +180,8 @@ class Config < Hash
 
   # Loads configuration from the supplied file path, or the default one if
   # none is specified.
-  # @param [String] path the path to the configuration file.
+  #
+  # @param path [String] the path to the configuration file.
   # @return [Rex::Parser::Ini] INI file parser.
   def self.load(path = nil)
     self.new.load(path)
@@ -172,7 +190,10 @@ class Config < Hash
   # Saves configuration to the path specified in the ConfigFile hash key or
   # the default path is one isn't specified.  The options should be group
   # references that have named value pairs.
-  # @param [Hash] opts Hash containing configuration options.
+  #
+  # @param opts [Hash] Hash containing configuration options.
+  # @option opts 'ConfigFile' [Hash] configuration file these options apply
+  #   to.
   # @return [void]
   # @example Save 'Cat' => 'Foo' in group 'ExampleGroup'
   #   save(
@@ -185,102 +206,119 @@ class Config < Hash
   end
 
   # Updates the config class' self with the default hash.
+  #
   # @return [Hash] the updated Hash.
   def initialize
     update(Defaults)
   end
 
   # Returns the installation root directory
+  #
   # @return [String] the installation root directory {InstallRoot}.
   def install_root
     InstallRoot
   end
 
   # Returns the configuration directory default.
+  #
   # @return [String] the root configuration directory.
   def config_directory
     self['ConfigDirectory']
   end
 
   # Returns the full path to the configuration file.
+  #
   # @return [String] path to the configuration file.
   def config_file
     config_directory + FileSep + self['ConfigFile']
   end
 
   # Returns the full path to the history file.
+  #
   # @return [String] path the history file.
   def history_file
     config_directory + FileSep + "history"
   end
 
   # Returns the global module directory.
+  #
   # @return [String] path to global module directory.
   def module_directory
     install_root + FileSep + self['ModuleDirectory']
   end
 
   # Returns the path that scripts can be loaded from.
+  #
   # @return [String] path to script directory.
   def script_directory
     install_root + FileSep + self['ScriptDirectory']
   end
 
   # Returns the directory that log files should be stored in.
+  #
   # @return [String] path to log directory.
   def log_directory
     config_directory + FileSep + self['LogDirectory']
   end
 
   # Returns the directory that plugins are stored in.
+  #
   # @return [String] path to plugin directory.
   def plugin_directory
     install_root + FileSep + self['PluginDirectory']
   end
 
   # Returns the directory in which session log files are to reside.
+  #
   # @return [String] path to session log directory.
   def session_log_directory
     config_directory + FileSep + self['SessionLogDirectory']
   end
 
   # Returns the directory in which captured data will reside.
+  #
   # @return [String] path to loot directory.
   def loot_directory
     config_directory + FileSep + self['LootDirectory']
   end
 
   # Returns the directory in which locally-generated data will reside.
+  #
   # @return [String] path to locally-generated data directory.
   def local_directory
     config_directory + FileSep + self['LocalDirectory']
   end
 
   # Returns the user-specific module base path
+  #
   # @return [String] path to user-specific modules directory.
   def user_module_directory
     config_directory + FileSep + "modules"
   end
 
   # Returns the user-specific plugin base path
+  #
   # @return [String] path to user-specific plugin directory.
   def user_plugin_directory
     config_directory + FileSep + "plugins"
   end
 
   # Returns the user-specific script base path
+  #
   # @return [String] path to user-specific script directory.
   def user_script_directory
     config_directory + FileSep + "scripts"
   end
 
   # Returns the data directory
+  #
   # @return [String] path to data directory.
   def data_directory
     install_root + FileSep + self['DataDirectory']
   end
 
   # Initializes configuration, creating directories as necessary.
+  #
   # @return [void]
   def init
     FileUtils.mkdir_p(module_directory)
@@ -295,7 +333,8 @@ class Config < Hash
 
   # Loads configuration from the supplied file path, or the default one if
   # none is specified.
-  # @param [String] path the path to the configuration file.
+  #
+  # @param path [String] the path to the configuration file.
   # @return [Rex::Parser::Ini] INI file parser.
   def load(path = nil)
     path = config_file if (!path)
@@ -306,7 +345,10 @@ class Config < Hash
   # Saves configuration to the path specified in the ConfigFile hash key or
   # the default path is one isn't specified.  The options should be group
   # references that have named value pairs.
-  # @param [Hash] opts Hash containing configuration options.
+  #
+  # @param opts [Hash] Hash containing configuration options.
+  # @option opts 'ConfigFile' [Hash] configuration file these options apply
+  #   to.
   # @return [void]
   # @example Save 'Cat' => 'Foo' in group 'ExampleGroup'
   #   save(

lib/msf/base/logging.rb

@@ -15,6 +15,7 @@ class Logging
   @@session_logging = false
 
   # Initialize logging.
+  #
   # @return [void]
   def self.init
     if (! @@initialized)
@@ -37,8 +38,9 @@ class Logging
   # Enables a log source of name src. Creates the .log file in the
   # configured directory if logging is not already enabled for this
   # source.
-  # @param [String] src log source name.
-  # @param [Integer] level logging level.
+  #
+  # @param src [String] log source name.
+  # @param level [Integer] logging level.
   # @return [void]
   def self.enable_log_source(src, level = 0)
     if (log_source_registered?(src) == false)
@@ -50,27 +52,31 @@ class Logging
   end
 
   # Stops logging for a given log source.
-  # @param [String] src the log source to disable.
+  #
+  # @param src [String] the log source to disable.
   # @return [Boolean] true if successful. false if not.
   def self.disable_log_source(src)
     deregister_log_source(src)
   end
 
   # Sets whether or not session logging is to be enabled.
-  # @param [Boolean] tf true if enabling. false if disabling.
+  #
+  # @param tf [Boolean] true if enabling. false if disabling.
   # @return [void]
   def self.enable_session_logging(tf)
     @@session_logging = tf
   end
 
   # Returns whether or not session logging is enabled.
+  #
   # @return [Boolean] true if enabled. false if disabled.
   def self.session_logging_enabled?
     @@session_logging || false
   end
 
   # Starts logging for a given session.
-  # @param [Msf::Session] session the session to start logging on.
+  #
+  # @param session [Msf::Session] the session to start logging on.
   # @return [void]
   def self.start_session_log(session)
     if (log_source_registered?(session.log_source) == false)
@@ -84,7 +90,8 @@ class Logging
   end
 
   # Stops logging for a given session.
-  # @param [Msf::Session] session the session to stop logging.
+  #
+  # @param session [Msf::Session] the session to stop logging.
   # @return [Boolean] true if sucessful. false if not.
   def self.stop_session_log(session)
     rlog("\n[*] Logging stopped: #{Time.now}\n\n", session.log_source)

lib/msf/base/persistent_storage.rb

@@ -6,18 +6,20 @@ module Msf
 # be used to store data that can later be reinitialized in a new instance
 # of the framework or to provide a simple mechanism for generating reports
 # of some form.
-# @abstract
+#
+# @abstract Subclass and override {#initialize}, {#store}, and {#fetch}.
 class PersistentStorage
 
-  #@private
   @@storage_classes = {}
 
   # Creates an instance of the storage class with the supplied name.  The
   # array supplied as an argument is passed to the constructor of the
   # associated class as a means of generic initialization.
-  # @param [String] name the name of the storage class.
-  # @param [Object] params the parameters to give the new class.
-  # @return [PersistentStorage, void] the newly created class or nil.
+  #
+  # @param name [String] the name of the storage class.
+  # @param params [Object] the parameters to give the new class.
+  # @return [PersistentStorage] the newly created class.
+  # @return [nil] if class has not been added through {.add_storage_class}.
   def self.create(name, *params)
     if (klass = @@storage_classes[name])
       klass.new(*params)
@@ -27,7 +29,8 @@ class PersistentStorage
   end
 
   # Stub initialization routine that takes the params passed to create.
-  # @param [Object] params the parameters to initialize with.
+  #
+  # @param params [Object] the parameters to initialize with.
   def initialize(*params)
   end
 
@@ -35,9 +38,10 @@ class PersistentStorage
   # framework instance to whatever medium the derived class implements.
   # If the derived class does not implement this method, the
   # NotImplementedError is raised.
-  # @raise [NotImpementedError] raised if not implemented.
-  # @param [Msf::Framework] framework framework state to store.
+  #
+  # @param framework [Msf::Framework] framework state to store.
   # @return [void] no implementation.
+  # @raise [NotImpementedError] raised if not implemented.
   def store(framework)
     raise NotImplementedError
   end
@@ -46,17 +50,19 @@ class PersistentStorage
   # that is stored in the persisted backing that the derived class
   # implements.  If the derived class does not implement this method, the
   # NotImplementedError is raised.
-  # @raise [NotImplementedError] raised if not implemented.
-  # @param [Msf::Framework] framework framework to restore state to.
+  #
+  # @param framework [Msf::Framework] framework to restore state to.
   # @return [void] no implementation.
+  # @raise [NotImplementedError] raised if not implemented.
   def fetch(framework)
     raise NotImplementedError
   end
 
   # This method adds a new storage class to the hash of storage classes that
   # can be created through create.
-  # @param [String] name the name of the storage class.
-  # @param [PersistentStorage] klass the storage class to add.
+  #
+  # @param name [String] the name of the storage class.
+  # @param klass [PersistentStorage] the storage class to add.
   # @return [void]
   def self.add_storage_class(name, klass)
     @@storage_classes[name] = klass

lib/msf/base/persistent_storage/flatfile.rb

@@ -10,9 +10,10 @@ class Flatfile < PersistentStorage
 
   # Initializes the flatfile for storage based on the parameters specified.
   # The hash must contain a FilePath attribute.
+  #
   # @overload initialize(path)
   #   Initializes the flatfile with the set path.
-  #   @param [String] path path of the flatfile.
+  #   @param path [String] path of the flatfile.
   def initialize(*params)
     raise ArgumentError, "You must specify a file path" if (params.length == 0)
 
@@ -21,7 +22,8 @@ class Flatfile < PersistentStorage
 
   # This method stores the current state of the framework in human readable
   # form to a flatfile.  This can be used as a reporting mechanism.
-  # @param [Msf:::Framework] framework the Framework to store.
+  #
+  # @param framework [Msf:::Framework] the Framework to store.
   # @return [void]
   def store(framework)
     # Open the supplied file path for writing.
@@ -40,7 +42,8 @@ protected
 
   # This method stores general information about the current state of the
   # framework instance.
-  # @param [Msf::Framework] framework the Framework to store.
+  #
+  # @param framework [Msf::Framework] the Framework to store.
   # @return [void]
   def store_general(framework)
     fd.print(

lib/msf/base/serializer/readable_text.rb

@@ -14,8 +14,9 @@ class ReadableText
 
   # Returns a formatted string that contains information about
   # the supplied module instance.
-  # @param [Msf::Module] mod the module to dump information for.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Module] the module to dump information for.
+  # @param indent [String] the indentation to use.
   # @return [String] formatted text output of the dump.
   def self.dump_module(mod, indent = "  ")
     case mod.type
@@ -37,11 +38,12 @@ class ReadableText
   end
 
   # Dumps an exploit's targets.
-  # @param [Msf::Exploit] mod the exploit module to dump targets
+  #
+  # @param mod [Msf::Exploit] the exploit module to dump targets
   #   for.
-  # @param [String] indent the indentation to use (only the length
+  # @param indent [String] the indentation to use (only the length
   #   matters).
-  # @param [String] h the string to display as the table heading.
+  # @param h [String] the string to display as the table heading.
   # @return [String] the string form of the table.
   def self.dump_exploit_targets(mod, indent = '', h = nil)
     tbl = Rex::Ui::Text::Table.new(
@@ -61,10 +63,11 @@ class ReadableText
   end
 
   # Dumps the exploit's selected target
-  # @param [Msf::Exploit] mod the exploit module.
-  # @param [String] indent the indentation to use (only the length
+  #
+  # @param mod [Msf::Exploit] the exploit module.
+  # @param indent [String] the indentation to use (only the length
   #   matters)
-  # @param [String] h the string to display as the table heading.
+  # @param h [String] the string to display as the table heading.
   # @return [String] the string form of the table.
   def self.dump_exploit_target(mod, indent = '', h = nil)
     tbl = Rex::Ui::Text::Table.new(
@@ -82,10 +85,11 @@ class ReadableText
   end
 
   # Dumps an auxiliary's actions
-  # @param [Msf::Auxiliary] mod the auxiliary module.
-  # @param [String] indent the indentation to use (only the length
+  #
+  # @param mod [Msf::Auxiliary] the auxiliary module.
+  # @param indent [String] the indentation to use (only the length
   #   matters)
-  # @param [String] h the string to display as the table heading.
+  # @param h [String] the string to display as the table heading.
   # @return [String] the string form of the table.
   def self.dump_auxiliary_actions(mod, indent = '', h = nil)
     tbl = Rex::Ui::Text::Table.new(
@@ -106,10 +110,11 @@ class ReadableText
 
   # Dumps the table of payloads that are compatible with the supplied
   # exploit.
-  # @param [Msf::Exploit] exploit the exploit module.
-  # @param [String] indent the indentation to use (only the length
+  # 
+  # @param exploit [Msf::Exploit] the exploit module.
+  # @param indent [String] the indentation to use (only the length
   #   matters)
-  # @param [String] h the string to display as the table heading.
+  # @param h [String] the string to display as the table heading.
   # @return [String] the string form of the table.
   def self.dump_compatible_payloads(exploit, indent = '', h = nil)
     tbl = Rex::Ui::Text::Table.new(
@@ -129,8 +134,9 @@ class ReadableText
   end
 
   # Dumps information about an exploit module.
-  # @param [Msf::Exploit] mod the exploit module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Exploit] the exploit module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_exploit_module(mod, indent = '')
     output  = "\n"
@@ -185,8 +191,9 @@ class ReadableText
   end
 
   # Dumps information about an auxiliary module.
-  # @param [Msf::Auxiliary] mod the auxiliary module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Auxiliary] the auxiliary module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_auxiliary_module(mod, indent = '')
     output  = "\n"
@@ -222,8 +229,9 @@ class ReadableText
   end
 
   # Dumps information about a payload module.
-  # @param [Msf::Payload] mod the payload module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Payload] the payload module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_payload_module(mod, indent = '')
     # General
@@ -260,8 +268,9 @@ class ReadableText
   end
 
   # Dumps information about a module, just the basics.
-  # @param [Msf::Module] mod the module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Module] the module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_basic_module(mod, indent = '')
     # General
@@ -293,14 +302,15 @@ class ReadableText
 
   end
 
-  #@private
+  #No current use
   def self.dump_generic_module(mod, indent = '')
   end
 
   # Dumps the list of options associated with the
   # supplied module.
-  # @param [Msf::Module] mod the module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Module] the module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_options(mod, indent = '')
     tbl = Rex::Ui::Text::Table.new(
@@ -328,8 +338,9 @@ class ReadableText
   end
 
   # Dumps the advanced options associated with the supplied module.
-  # @param [Msf::Module] mod the module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Module] the module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_advanced_options(mod, indent = '')
     output = ''
@@ -353,8 +364,9 @@ class ReadableText
   end
 
   # Dumps the evasion options associated with the supplied module.
-  # @param [Msf::Module] mod the module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Module] the module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_evasion_options(mod, indent = '')
     output = ''
@@ -379,8 +391,9 @@ class ReadableText
   end
 
   # Dumps the references associated with the supplied module.
-  # @param [Msf::Module] mod the module.
-  # @param [String] indent the indentation to use.
+  #
+  # @param mod [Msf::Module] the module.
+  # @param indent [String] the indentation to use.
   # @return [String] the string form of the information.
   def self.dump_references(mod, indent = '')
     output = ''
@@ -397,10 +410,11 @@ class ReadableText
   end
 
   # Dumps the contents of a datastore.
-  # @param [String] name displayed as the table header.
-  # @param [Msf::DataStore] ds the DataStore to dump.
-  # @param [Integer] indent the indentation size.
-  # @param [Integer] col the column width.
+  #
+  # @param name [String] displayed as the table header.
+  # @param ds [Msf::DataStore] the DataStore to dump.
+  # @param indent [Integer] the indentation size.
+  # @param col [Integer] the column width.
   # @return [String] the formatted DataStore contents.
   def self.dump_datastore(name, ds, indent = DefaultIndent, col = DefaultColumnWrap)
     tbl = Rex::Ui::Text::Table.new(
@@ -420,14 +434,15 @@ class ReadableText
   end
 
   # Dumps the list of active sessions.
-  # @param [Msf::Framework] framework the framework to dump.
-  # @param [Hash] opts the options to dump with.
-  # @option opts [Array] :session_ids the list of sessions to dump (no
+  #
+  # @param framework [Msf::Framework] the framework to dump.
+  # @param opts [Hash] the options to dump with.
+  # @option opts :session_ids [Array] the list of sessions to dump (no
   #   effect).
-  # @option opts [Boolean] :verbose gives more information if set to
+  # @option opts :verbose [Boolean] gives more information if set to
   #   true.
-  # @option opts [Integer] :indent set the indentation amount.
-  # @option opts [Integer] :col the column wrap width.
+  # @option opts :indent [Integer] set the indentation amount.
+  # @option opts :col [Integer] the column wrap width.
   # @return [String] the formatted list of sessions.
   def self.dump_sessions(framework, opts={})
     ids = (opts[:session_ids] || framework.sessions.keys).sort
@@ -472,11 +487,12 @@ class ReadableText
   end
 
   # Dumps the list of running jobs.
-  # @param [Msf::Framework] framework the framework.
-  # @param [Boolean] verbose if true, also prints the payload, LPORT, URIPATH 
+  #
+  # @param framework [Msf::Framework] the framework.
+  # @param verbose [Boolean] if true, also prints the payload, LPORT, URIPATH 
   #   and start time, if they exist, for each job.
-  # @param [Integer] indent the indentation amount.
-  # @param [Integer] col the column wrap width.
+  # @param indent [Integer] the indentation amount.
+  # @param col [Integer] the column wrap width.
   # @return [String] the formatted list of running jobs.
   def self.dump_jobs(framework, verbose = false, indent = DefaultIndent, col = DefaultColumnWrap)
     columns = [ 'Id', 'Name' ]
@@ -514,12 +530,12 @@ class ReadableText
     return framework.jobs.keys.length > 0 ? tbl.to_s : "#{tbl.header_to_s}No active jobs.\n"
   end
 
-  #
   # Jacked from Ernest Ellingson <erne [at] powernav.com>, modified
   # a bit to add indention
-  # @param [String] str the string to wrap.
-  # @param [Integer] indent the indentation amount.
-  # @param [Integer] col the column wrap width.
+  #
+  # @param str [String] the string to wrap.
+  # @param indent [Integer] the indentation amount.
+  # @param col [Integer] the column wrap width.
   # @return [String] the wrapped string.
   def self.word_wrap(str, indent = DefaultIndent, col = DefaultColumnWrap)
     return Rex::Text.wordwrap(str, indent, col)