Reuse appropriate terminology in docs

[#47720609]

Fix some docs and variable names to make it clearer when methods are
expecting module instance and module classes.  Change some 'name'
variables to 'reference_name' since that's the proper terminology.

Author: limhoff-r7

lib/msf/core/module_manager.rb

@@ -144,9 +144,9 @@ def initialize(framework, types=Msf::MODULE_TYPES)
     # aux modules may wish to run such that they can collect more
     # information about the host that was detected.
     #
-    # @param mod [Class] A subclass of Msf::Module
+    # @param klass [Class<Msf::Module>] The module class
     # @return [void]
-    def auto_subscribe_module(mod)
+    def auto_subscribe_module(klass)
       # If auto-subscribe has been disabled
       if (framework.datastore['DisableAutoSubscribe'] and
           framework.datastore['DisableAutoSubscribe'] =~ /^(y|1|t)/)
@@ -160,15 +160,15 @@ def auto_subscribe_module(mod)
       #
       # Exploit event subscriber check
       #
-      if (mod.include?(Msf::ExploitEvent) == true)
-        framework.events.add_exploit_subscriber((inst) ? inst : (inst = mod.new))
+      if (klass.include?(Msf::ExploitEvent) == true)
+        framework.events.add_exploit_subscriber((inst) ? inst : (inst = klass.new))
       end
 
       #
       # Session event subscriber check
       #
-      if (mod.include?(Msf::SessionEvent) == true)
-        framework.events.add_session_subscriber((inst) ? inst : (inst = mod.new))
+      if (klass.include?(Msf::SessionEvent) == true)
+        framework.events.add_session_subscriber((inst) ? inst : (inst = klass.new))
       end
     end
 

lib/msf/core/module_manager/loading.rb

@@ -53,20 +53,29 @@ def file_changed?(path)
 
   attr_accessor :module_load_error_by_path
 
-  # Called when a module is initially loaded such that it can be
-  # categorized accordingly.
+  # Called when a module is initially loaded such that it can be categorized
+  # accordingly.
   #
-  def on_module_load(mod, type, name, modinfo)
-    dup = module_set_by_type[type].add_module(mod, name, modinfo)
+  # @param klass (see Msf::ModuleSet#add_module)
+  # @param type [String] The module type.
+  # @param reference_name (see Msf::ModuleSet#add_module)
+  # @param info [Hash{String => Array}] additional information about the module
+  # @option info [Array<String>] 'files' List of paths to the ruby source files
+  #   where +klass+ is defined.
+  # @option info [Array<String>] 'paths' List of module reference names.
+  # @option info [String] 'type' The module type, should match positional
+  #   +type+ argument.
+  # @return [void]
+  def on_module_load(klass, type, reference_name, info={})
+    module_set = module_set_by_type[type]
+    annotated_klass = module_set.add_module(klass, reference_name, info)
 
     # Automatically subscribe a wrapper around this module to the necessary
     # event providers based on whatever events it wishes to receive.
-    auto_subscribe_module(dup)
+    auto_subscribe_module(annotated_klass)
 
     # Notify the framework that a module was loaded
-    framework.events.on_module_load(name, dup)
-
-    dup
+    framework.events.on_module_load(reference_name, annotated_klass)
   end
 
   protected

lib/msf/core/module_set.rb

@@ -31,26 +31,26 @@ def [](name)
     super
   end
 
-  # Create an instance of the supplied module by its name
+  # Create an instance of the supplied module by its reference name
   #
-  # @param name [String] The module reference name.
+  # @param reference_name [String] The module reference name.
   # @return [Msf::Module,nil] Instance of the named module or nil if it
   #   could not be created.
-  def create(name)
-    klass = fetch(name, nil)
+  def create(reference_name)
+    klass = fetch(reference_name, nil)
     instance = nil
 
     # If there is no module associated with this class, then try to demand
     # load it.
     if klass.nil? or klass == Msf::SymbolicModule
-      framework.modules.load_cached_module(module_type, name)
+      framework.modules.load_cached_module(module_type, reference_name)
 
       recalculate
 
-      klass = fetch(name, nil)
+      klass = fetch(reference_name, nil)
     end
 
-    # If the klass is valid for this name, try to create it
+    # If the klass is valid for this reference_name, try to create it
     unless klass.nil? or klass == Msf::SymbolicModule
       instance = klass.new
     end
@@ -67,7 +67,7 @@ def create(name)
   # "can't add a new key into hash during iteration"
   #
   # @yield [module_reference_name, module]
-  # @yieldparam [String] module_reference_name the name of the module.
+  # @yieldparam [String] module_reference_name the reference_name of the module.
   # @yieldparam [Class] module The module class: a subclass of Msf::Module.
   # @return [void]
   def each(&block)
@@ -167,43 +167,47 @@ def on_module_reload(mod)
   def recalculate
   end
 
-  # Checks to see if the supplied module name is valid.
+  # Checks to see if the supplied module reference name is valid.
   #
+  # @param reference_name [String] The module reference name.
   # @return [true] if the module can be {#create created} and cached.
   # @return [false] otherwise
-  def valid?(name)
-    create(name)
-    (self[name]) ? true : false
+  def valid?(reference_name)
+    create(reference_name)
+    (self[reference_name]) ? true : false
   end
 
-  # Adds a module with a the supplied name.
+  # Adds a module with a the supplied reference_name.
   #
-  # @param [Class] mod The module class: a subclass of Msf::Module.
-  # @param [String] name The module reference name
-  # @param [Hash{String => Object}] modinfo optional module information
-  # @return [Class] The mod parameter modified to have {Msf::Module#framework}, {Msf::Module#refname},
-  #   {Msf::Module#file_path}, and {Msf::Module#orig_cls} set.
-  def add_module(mod, name, modinfo = nil)
-    # Set the module's name so that it can be referenced when
+  # @param [Class<Msf::Module>] klass The module class.
+  # @param [String] reference_name The module reference name.
+  # @param [Hash{String => Object}] info optional module information.
+  # @option info [Array<String>] 'files' List of paths to files that defined
+  #   +klass+.
+  # @return [Class] The klass parameter modified to have
+  #   {Msf::Module#framework}, {Msf::Module#refname}, {Msf::Module#file_path},
+  #   and {Msf::Module#orig_cls} set.
+  def add_module(klass, reference_name, info = {})
+    # Set the module's reference_name so that it can be referenced when
     # instances are created.
-    mod.framework = framework
-    mod.refname   = name
-    mod.file_path = ((modinfo and modinfo['files']) ? modinfo['files'][0] : nil)
-    mod.orig_cls  = mod
+    klass.framework = framework
+    klass.refname   = reference_name
+    klass.file_path = ((info and info['files']) ? info['files'][0] : nil)
+    klass.orig_cls  = klass
 
     # don't want to trigger a create, so use fetch
-    cached_module = self.fetch(name, nil)
+    cached_module = self.fetch(reference_name, nil)
 
     if (cached_module and cached_module != Msf::SymbolicModule)
-      ambiguous_module_reference_name_set.add(name)
+      ambiguous_module_reference_name_set.add(reference_name)
 
       # TODO this isn't terribly helpful since the refnames will always match, that's why they are ambiguous.
-      wlog("The module #{mod.refname} is ambiguous with #{self[name].refname}.")
+      wlog("The module #{klass.refname} is ambiguous with #{self[reference_name].refname}.")
     end
 
-    self[name] = mod
+    self[reference_name] = klass
 
-    mod
+    klass
   end
 
   protected

spec/support/shared/examples/msf/module_manager/loading.rb

@@ -140,10 +140,6 @@ def on_module_load
 				module_set.stub(:add_module).and_return(annotated_class)
 			end
 
-			it 'should return annotated class from Msf::ModuleSet#add_module' do
-				on_module_load.should == annotated_class
-			end
-
 			it 'should pass annotated class to Msf::ModuleManager#auto_subscribe_module' do
 				module_manager.should_receive(:auto_subscribe_module).with(annotated_class)