(PDOC-37) Test errors are output properly

Also comment out a statement which we frequently use for debugging which
snuck in by accident.

lib/puppet/face/strings.rb

@@ -50,7 +50,11 @@ Puppet::Face.define(:strings, '0.0.1') do
       # For now, assume the remaining positional args are a list of manifest
       # and ruby files to parse.
       yard_args = (args.empty? ? MODULE_SOURCEFILES : args)
-      class YARD::Logger; def progress(*args); end; end
+
+      # This line monkeypatches yard's progress indicator so it doesn't write
+      # all over the terminal. This should definitely not be in real code, but
+      # it's very handy for debugging with pry
+      #class YARD::Logger; def progress(*args); end; end
 
       yardoc_actions.generate_documentation(*yard_args)
     end

spec/unit/puppet_x/puppetlabs/strings/yard/puppet_4x_function_handler_spec.rb

@@ -54,12 +54,21 @@ describe PuppetX::PuppetLabs::Strings::YARD::Handlers::Puppet4xFunctionHandler d
     expect(the_namespace).to document_a(:type => :puppetnamespace)
   end
 
-  it "should not add anything to the Registry if incorrect ruby code is present" do
+  it "should issue a warning if the parameter names do not match the docstring" do
+      expected_output_not_a_param = "[warn]: @param tag has unknown parameter" +
+        " name: not_a_param \n    in file `(stdin)' near line 3"
+      expected_output_also_not_a_param = "[warn]: @param tag has unknown " +
+        "parameter name: also_not_a_param \n    in file `(stdin)' near line 3"
+      expect {
         parse <<-RUBY
-        # The summary
+          # @param not_a_param [Integer] the first number to be compared
-        This is not ruby code
+          # @param also_not_a_param [Integer] the second number to be compared
+          Puppet::Functions.create_function(:max) do
+            def max(num_a, num_b)
+              num_a >= num_b ? num_a : num_b
+            end
+          end
         RUBY
-
+      }.to output("#{expected_output_not_a_param}\n#{expected_output_also_not_a_param}\n").to_stdout_from_any_process
-    expect(YARD::Registry.all).to be_empty
   end
 end

spec/unit/puppet_x/puppetlabs/strings/yard/template_helper_spec.rb

@@ -0,0 +1,59 @@
+require 'spec_helper'
+require 'puppet_x/puppetlabs/strings/yard/templates/default/template_helper'
+require 'puppet_x/puppetlabs/strings/yard/code_objects/puppet_namespace_object'
+require 'strings_spec/parsing'
+
+describe TemplateHelper do
+  it "should not print any warning if the tags and parameters match" do
+    th = TemplateHelper.new
+
+    # Case 0: If the documented tags do include the parameter,
+    # nothing is printed
+    tag0 = YARD::Tags::Tag.new(:param, 'a_parameter')
+    tag0.name = 'a_parameter'
+    obj0 = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet3xFunctions')
+    obj0.add_tag tag0
+    obj0.parameters = [['a_parameter']]
+    expect { th.check_parameters_match_docs obj0 }.to output("").to_stderr_from_any_process
+
+    # The docstring is still alive between tests. Clear the tags registered with
+    # it so the tags won't persist between tests.
+    obj0.docstring.instance_variable_set("@tags", [])
+  end
+
+  it "should print the warning with no location data if the tags and " +
+      "parameters differ and the location data is not properly formed" do
+    th = TemplateHelper.new
+    # Case 1: If the parameter and tag differ and the location is not properly
+    # formed, print out the warning with no location data
+    tag1 = YARD::Tags::Tag.new(:param, 'aa_parameter')
+    tag1.name = 'aa_parameter'
+    obj1 = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet3xFunctions')
+    obj1.add_tag tag1
+    obj1.parameters = [['b_parameter']]
+    expect { th.check_parameters_match_docs obj1 }.to output("[warn]: The parameter aa_parameter is documented, but doesn't exist in your code. Sorry, the file and line number could not be determined.\n").to_stderr_from_any_process
+
+    # The docstring is still alive between tests. Clear the tags registered with
+    # it so the tags won't persist between tests.
+    obj1.docstring.instance_variable_set("@tags", [])
+  end
+
+  it "should print the warning with location data if the tags and parameters " +
+      "differ and the location data is properly formed" do
+    th = TemplateHelper.new
+    # Case 2: If the parameter and tag differ and the location is properly
+    # formed, print out the warning with no location data
+    tag2 = YARD::Tags::Tag.new(:param, 'aaa_parameter')
+    tag2.name = 'aaa_parameter'
+    obj2 = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet3xFunctions')
+    obj2.files = [['some_file.pp', 42]]
+    obj2.add_tag tag2
+    obj2.parameters = [['b_parameter']]
+    expect { th.check_parameters_match_docs obj2 }.to output("[warn]: The parameter aaa_parameter is documented, but doesn't exist in your code, in file some_file.pp near line 42\n").to_stderr_from_any_process
+
+    # The docstring is still alive between tests. Clear the tags registered with
+    # it so the tags won't persist between tests.
+    obj2.docstring.instance_variable_set("@tags", [])
+  end
+
+end