From e26cb69d361c783b8ee804364b4d773cec07b288 Mon Sep 17 00:00:00 2001 From: Ian Kronquist Date: Fri, 11 Sep 2015 14:14:00 -0700 Subject: [PATCH] (PDOC-49) Improve warnings 1. Long warning should be broken onto multiple lines. 2. Warnings should begin with `[warn]:` --- .../yard/templates/default/template_helper.rb | 28 +++++++++++-------- .../strings/yard/host_class_handler_spec.rb | 2 +- .../yard/puppet_4x_function_handler_spec.rb | 14 +++++----- .../strings/yard/template_helper_spec.rb | 12 ++++---- 4 files changed, 31 insertions(+), 25 deletions(-) diff --git a/lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb b/lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb index dca57e9..1f3608d 100644 --- a/lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb +++ b/lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb @@ -137,21 +137,21 @@ class TemplateHelper # Get the locations where the object can be found. We only care about # the first one. locations = object.files + warning = <<-EOS +[warn]: @param tag types do not match the code. The #{param[:name]} + parameter is declared as types #{param[:types]} in the docstring, + but the code specifies the types #{actual_types.inspect} + EOS + # If the locations aren't in the shape we expect then report that # the file number couldn't be determined. if locations.length >= 1 and locations[0].length == 2 file = locations[0][0] line = locations[0][1] - warning = "@param tag types do not match the code. The " + - "#{param[:name]} parameter is declared as types #{param[:types]} in " + - "the docstring, but the code specifies the types " + - "#{actual_types.inspect} in file #{file} near line #{line}" + warning += " in the file #{file} near line #{line}." else - warning = "@param tag types do not match the code. The " + - "#{param[:name]} parameter is declared as types #{param[:types]} in " + - "the docstring, but the code specifies the types " + - "#{actual_types.inspect} Sorry, the file and line number could" + - "not be determined." + warning += " Sorry, the file and line number could " + + "not be determined." end $stderr.puts warning end @@ -176,9 +176,15 @@ class TemplateHelper if locations.length >= 1 and locations[0].length == 2 file_name = locations[0][0] line_number = locations[0][1] - $stderr.puts "[warn]: The parameter #{tag.name} is documented, but doesn't exist in your code, in file #{file_name} near line #{line_number}" + $stderr.puts <<-EOS +[warn]: The parameter #{tag.name} is documented, but doesn't exist in + your code, in file #{file_name} near line #{line_number}. +EOS else - $stderr.puts "[warn]: The parameter #{tag.name} is documented, but doesn't exist in your code. Sorry, the file and line number could not be determined." + $stderr.puts <<-EOS +[warn]: The parameter #{tag.name} is documented, but doesn't exist in + your code. Sorry, the file and line number could not be determined. +EOS end end end diff --git a/spec/unit/puppet_x/puppetlabs/strings/yard/host_class_handler_spec.rb b/spec/unit/puppet_x/puppetlabs/strings/yard/host_class_handler_spec.rb index 57cbb37..96e9186 100644 --- a/spec/unit/puppet_x/puppetlabs/strings/yard/host_class_handler_spec.rb +++ b/spec/unit/puppet_x/puppetlabs/strings/yard/host_class_handler_spec.rb @@ -79,7 +79,7 @@ Puppet Types: 0 ( 0 undocumented) Puppet Providers: 0 ( 0 undocumented) 100.00% documented output - expected_stderr = "@param tag types do not match the code. The ident parameter is declared as types [\"Float\"] in the docstring, but the code specifies the types [Puppet::Pops::Types::PStringType] in file manifests/init.pp near line 2\n" + expected_stderr = "[warn]: @param tag types do not match the code. The ident\n parameter is declared as types [\"Float\"] in the docstring,\n but the code specifies the types [Puppet::Pops::Types::PStringType]\n in the file manifests/init.pp near line 2.\n" expect { expect { diff --git a/spec/unit/puppet_x/puppetlabs/strings/yard/puppet_4x_function_handler_spec.rb b/spec/unit/puppet_x/puppetlabs/strings/yard/puppet_4x_function_handler_spec.rb index acd229d..6dcf9d4 100644 --- a/spec/unit/puppet_x/puppetlabs/strings/yard/puppet_4x_function_handler_spec.rb +++ b/spec/unit/puppet_x/puppetlabs/strings/yard/puppet_4x_function_handler_spec.rb @@ -57,8 +57,8 @@ describe PuppetX::PuppetLabs::Strings::YARD::Handlers::Puppet4xFunctionHandler d end it "should issue a warning if the parameter names do not match the docstring" do - expected_output_not_a_param = "[warn]: The parameter not_a_param is documented, but doesn't exist in your code, in file lib/test.rb near line 3" - expected_output_also_not_a_param = "[warn]: The parameter also_not_a_param is documented, but doesn't exist in your code, in file lib/test.rb near line 3" + expected_output_not_a_param = "[warn]: The parameter not_a_param is documented, but doesn't exist in\n your code, in file lib/test.rb near line 3." + expected_output_also_not_a_param = "[warn]: The parameter also_not_a_param is documented, but doesn't exist in\n your code, in file lib/test.rb near line 3." expect { expect { PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ') do |tmp| @@ -95,9 +95,9 @@ describe PuppetX::PuppetLabs::Strings::YARD::Handlers::Puppet4xFunctionHandler d it "should issue a warning when there are parametarized types and parameter names differ" do expected_output_not_num_a = "[warn]: @param tag has unknown parameter" + - " name: not_num_a \n in file `(stdin)' near line 3" - expected_output_not_a_param = "[warn]: The parameter not_a_param is documented, but doesn't exist in your code, in file lib/test.rb near line 3" - expected_output_also_not_a_param = "[warn]: The parameter also_not_a_param is documented, but doesn't exist in your code, in file lib/test.rb near line 3" + " name: not_num_a \n in file `(stdin)' near line 3." + expected_output_not_a_param = "[warn]: The parameter not_a_param is documented, but doesn't exist in\n your code, in file lib/test.rb near line 3." + expected_output_also_not_a_param = "[warn]: The parameter also_not_a_param is documented, but doesn't exist in\n your code, in file lib/test.rb near line 3." expect { expect { PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ-with-types') do |tmp| @@ -110,8 +110,8 @@ describe PuppetX::PuppetLabs::Strings::YARD::Handlers::Puppet4xFunctionHandler d it "should issue a warning if the parameter names do not match the docstring in dispatch method" do - expected_output_not_a_param = "[warn]: The parameter not_a_param is documented, but doesn't exist in your code, in file lib/test.rb near line 3" - expected_output_also_not_a_param = "[warn]: The parameter also_not_a_param is documented, but doesn't exist in your code, in file lib/test.rb near line 3" + expected_output_not_a_param = "[warn]: The parameter not_a_param is documented, but doesn't exist in\n your code, in file lib/test.rb near line 3." + expected_output_also_not_a_param = "[warn]: The parameter also_not_a_param is documented, but doesn't exist in\n your code, in file lib/test.rb near line 3." expect { expect { PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ-with-dispatch') do |tmp| diff --git a/spec/unit/puppet_x/puppetlabs/strings/yard/template_helper_spec.rb b/spec/unit/puppet_x/puppetlabs/strings/yard/template_helper_spec.rb index ed7e68d..6772d7d 100644 --- a/spec/unit/puppet_x/puppetlabs/strings/yard/template_helper_spec.rb +++ b/spec/unit/puppet_x/puppetlabs/strings/yard/template_helper_spec.rb @@ -31,7 +31,7 @@ describe TemplateHelper do 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 + expect { th.check_parameters_match_docs obj1 }.to output("[warn]: The parameter aa_parameter is documented, but doesn't exist in\n 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. @@ -49,7 +49,7 @@ describe TemplateHelper do 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 + expect { th.check_parameters_match_docs obj2 }.to output("[warn]: The parameter aaa_parameter is documented, but doesn't exist in\n 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. @@ -57,10 +57,10 @@ describe TemplateHelper do end it "should issue a warning if the parameter types do not match the docstring in dispatch method" do - expected_output_not_a_param = "@param tag types do not match the" + - " code. The arg1 parameter is declared as types [\"Integer\"] in the " + - "docstring, but the code specifies the types [\"Optional[String]\"] " + - "in file test near line 0\n" + expected_output_not_a_param = "[warn]: @param tag types do not match the" + + " code. The arg1\n parameter is declared as types [\"Integer\"] in the " + + "docstring,\n but the code specifies the types [\"Optional[String]\"]" + + "\n in the file test near line 0.\n" object = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet4xFunctions') object.files = [['test', 0]] object.type_info = [{