(PDOC-3) Change actions from module to class

Refactor the actions module so that it is a class. This is important
because it allows us to keep `Puppet[]` calls out of the library and
have them in the face itself. Additionally, move a few things around
(like `check_required_features` since it makes require statements
cleaner) and clean up some comments.

lib/puppet/face/strings.rb

@@ -1,11 +1,31 @@
 require 'puppet/face'
 require 'puppetx/puppetlabs/strings/actions'
 
-include Puppetx::PuppetLabs::Strings::Actions
-
 Puppet::Face.define(:strings, '0.0.1') do
   summary "Generate Puppet documentation with YARD."
 
+  # Ensures that the user has the needed features to use puppet strings
+  def check_required_features
+    unless Puppet.features.yard?
+      raise RuntimeError, "The 'yard' gem must be installed in order to use this face."
+    end
+
+    unless Puppet.features.rgen?
+      raise RuntimeError, "The 'rgen' gem must be installed in order to use this face."
+    end
+
+    if RUBY_VERSION.match(/^1\.8/)
+      raise RuntimeError, "This face requires Ruby 1.9 or greater."
+    end
+  end
+
+  # A list of globs that generates the default list of module files from which
+  # documentation can be extracted.
+  #
+  # TODO: It would be awesome if we could somehow override/append to the
+  # default file list that YARD uses. Consider an upstream PR for this.
+  MODULE_SOURCEFILES = ['manifests/**/*.pp', 'lib/**/*.rb']
+
   action(:yardoc) do
     default
 
@@ -14,7 +34,8 @@ Puppet::Face.define(:strings, '0.0.1') do
 
     when_invoked do |*args|
       check_required_features
-      require 'puppetx/puppetlabs/strings/yard/plugin'
+
+      yardoc_actions = Puppetx::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace])
 
       # The last element of the argument array should be the options hash.
       #
@@ -28,7 +49,7 @@ Puppet::Face.define(:strings, '0.0.1') do
       # and ruby files to parse.
       yard_args = (args.empty? ? MODULE_SOURCEFILES : args)
 
-      generate_documentation(*yard_args)
+      yardoc_actions.generate_documentation(*yard_args)
     end
   end
 
@@ -42,7 +63,8 @@ Puppet::Face.define(:strings, '0.0.1') do
 
     when_invoked do |*args|
       check_required_features
-      require 'puppetx/puppetlabs/strings/yard/plugin'
+
+      server_actions = Puppetx::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace])
 
       opts = args.pop
 
@@ -51,9 +73,9 @@ Puppet::Face.define(:strings, '0.0.1') do
       # FIXME: This is pretty inefficient as it forcibly re-generates the YARD
       # indicies each time the server is started. However, it ensures things are
       # generated properly.
-      module_list = index_documentation_for_modules(module_names)
+      module_list = server_actions.index_documentation_for_modules(module_names, MODULE_SOURCEFILES)
 
-      module_tuples = generate_module_tuples(module_list)
+      module_tuples = server_actions.generate_module_tuples(module_list)
 
       module_tuples.map! do |mod|
         [mod[:name], mod[:index_path]]
@@ -65,7 +87,7 @@ Puppet::Face.define(:strings, '0.0.1') do
       yard_args = %w[-m -q] + module_tuples.flatten
       merge_puppet_args!(yard_args)
 
-      serve_documentation(*yard_args)
+      server_actions.serve_documentation(*yard_args)
     end
   end
 end

lib/puppetx/puppetlabs/strings/actions.rb

@@ -1,36 +1,24 @@
 require 'puppetx/puppetlabs/strings'
+require 'puppetx/puppetlabs/strings/yard/plugin'
 
-module Puppetx::PuppetLabs::Strings::Actions
+class Puppetx::PuppetLabs::Strings::Actions
+
+  # Creates a new instance of the Actions class by determining
+  # whether or not debug and backtrace arguments should be sent
+  # to YARD
+  def initialize(puppet_debug, puppet_backtrace)
+    @debug = puppet_debug
+    @backtrace = puppet_backtrace
+  end
 
   # Holds the name of a module and the file path to its YARD index
   ModuleIndex = Struct.new(:name, :index_path)
 
-  # A list of globs that generates the default list of module files from which
-  # documentation can be extracted.
-  #
-  # TODO: It would be awesome if we could somehow override/append to the
-  # default file list that YARD uses. Consider an upstream PR for this.
-  MODULE_SOURCEFILES = ['manifests/**/*.pp', 'lib/**/*.rb']
-
-  # Ensures that the user has the needed features to use puppet strings
-  def check_required_features
-    unless Puppet.features.yard?
-      raise RuntimeError, "The 'yard' gem must be installed in order to use this face."
-    end
-
-    unless Puppet.features.rgen?
-      raise RuntimeError, "The 'rgen' gem must be installed in order to use this face."
-    end
-
-    if RUBY_VERSION.match(/^1\.8/)
-      raise RuntimeError, "This face requires Ruby 1.9 or greater."
-    end
-  end
 
   # Maps things like the Puppet `--debug` flag to YARD options.
   def merge_puppet_args!(yard_args)
-    yard_args.unshift '--debug'     if Puppet[:debug]
+    yard_args.unshift '--debug'     if @debug
-    yard_args.unshift '--backtrace' if Puppet[:trace]
+    yard_args.unshift '--backtrace' if @backtrace
 
     yard_args
   end
@@ -41,20 +29,20 @@ module Puppetx::PuppetLabs::Strings::Actions
   #
   # @return [Array<Module>] the modules to be documented
   #
-  # @param [Array<String>] a list of the module source files
+  # @param [Array<String>] module_names a list of the module source files
-  def index_documentation_for_modules(module_names)
+  # @param [Array<String>] module_sourcefiles default list of module files
+  def index_documentation_for_modules(module_names, module_sourcefiles)
     # NOTE: The return value of the `module` Face seems to have changed in
     # 3.6.x. This part of the code will blow up if run under an earlier
     # version of Puppet.
     modules = Puppet::Face[:module, :current].list
     module_list = modules[:modules_by_path].values.flatten
 
-    # TODO: Can use select! if Ruby 1.8.7 support is dropped.
     module_list.select! {|m| module_names.include? m.name} unless module_names.empty?
 
     # Invoke `yardoc` with -n so that it doesn't generate any HTML output but
     # does build a `.yardoc` index that other tools can generate output from.
-    yard_args = %w[--no-stats -n] + MODULE_SOURCEFILES
+    yard_args = %w[--no-stats -n] + module_sourcefiles
     merge_puppet_args!(yard_args)
 
     module_list.each do |m|
@@ -74,7 +62,7 @@ module Puppetx::PuppetLabs::Strings::Actions
   # to produce documentation for. Each ModuleIndex contains the module name
   # and the path to its YARD index
   #
-  # @param [Array<String>] a list of the module source files
+  # @param [Array<String>] module_list a list of the module source files
   def generate_module_tuples(module_list)
     module_list.map do |mod|
       name = (mod.forge_name || mod.name).gsub('/', '-')
@@ -87,7 +75,7 @@ module Puppetx::PuppetLabs::Strings::Actions
   # Hands off the needed information to YARD so it may
   # serve the documentation
   #
-  # @param [Array<String>] a list of all the arguments to pass to YARD
+  # @param [Array<String>] yard_args a list of all the arguments to pass to YARD
   def serve_documentation(*yard_args)
     merge_puppet_args!(yard_args)
     YARD::CLI::Server.run(*yard_args)
@@ -96,7 +84,7 @@ module Puppetx::PuppetLabs::Strings::Actions
   # Hands off the needed information to YARD so it may
   # generate the documentation
   #
-  # @param [Array<String>] a list of all the arguments to pass to YARD
+  # @param [Array<String>] yard_args a list of all the arguments to pass to YARD
   def generate_documentation(*yard_args)
     merge_puppet_args!(yard_args)
     YARD::CLI::Yardoc.run(*yard_args)