Merge pull request #57 from iankronquist/improve-warnings-pdoc-49

(PDOC-49) Improve warnings
This commit is contained in:
Hailee Kenney 2015-09-11 14:50:04 -07:00
commit 782fee5d0b
4 changed files with 31 additions and 25 deletions

View File

@ -137,21 +137,21 @@ class TemplateHelper
# Get the locations where the object can be found. We only care about # Get the locations where the object can be found. We only care about
# the first one. # the first one.
locations = object.files 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 # If the locations aren't in the shape we expect then report that
# the file number couldn't be determined. # the file number couldn't be determined.
if locations.length >= 1 and locations[0].length == 2 if locations.length >= 1 and locations[0].length == 2
file = locations[0][0] file = locations[0][0]
line = locations[0][1] line = locations[0][1]
warning = "@param tag types do not match the code. The " + warning += " in the file #{file} near line #{line}."
"#{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}"
else else
warning = "@param tag types do not match the code. The " + warning += " Sorry, the file and line number could " +
"#{param[:name]} parameter is declared as types #{param[:types]} in " + "not be determined."
"the docstring, but the code specifies the types " +
"#{actual_types.inspect} Sorry, the file and line number could" +
"not be determined."
end end
$stderr.puts warning $stderr.puts warning
end end
@ -176,9 +176,15 @@ class TemplateHelper
if locations.length >= 1 and locations[0].length == 2 if locations.length >= 1 and locations[0].length == 2
file_name = locations[0][0] file_name = locations[0][0]
line_number = locations[0][1] 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 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 end
end end

View File

@ -79,7 +79,7 @@ Puppet Types: 0 ( 0 undocumented)
Puppet Providers: 0 ( 0 undocumented) Puppet Providers: 0 ( 0 undocumented)
100.00% documented 100.00% documented
output 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 {
expect { expect {

View File

@ -57,8 +57,8 @@ describe PuppetX::PuppetLabs::Strings::YARD::Handlers::Puppet4xFunctionHandler d
end end
it "should issue a warning if the parameter names do not match the docstring" do 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_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 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 {
expect { expect {
PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ') do |tmp| 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 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" + expected_output_not_num_a = "[warn]: @param tag has unknown parameter" +
" name: not_num_a \n in file `(stdin)' 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 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 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 {
expect { expect {
PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ-with-types') do |tmp| 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 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_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 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 {
expect { expect {
PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ-with-dispatch') do |tmp| PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ-with-dispatch') do |tmp|

View File

@ -31,7 +31,7 @@ describe TemplateHelper do
obj1 = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet3xFunctions') obj1 = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet3xFunctions')
obj1.add_tag tag1 obj1.add_tag tag1
obj1.parameters = [['b_parameter']] 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 # The docstring is still alive between tests. Clear the tags registered with
# it so the tags won't persist between tests. # it so the tags won't persist between tests.
@ -49,7 +49,7 @@ describe TemplateHelper do
obj2.files = [['some_file.pp', 42]] obj2.files = [['some_file.pp', 42]]
obj2.add_tag tag2 obj2.add_tag tag2
obj2.parameters = [['b_parameter']] 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 # The docstring is still alive between tests. Clear the tags registered with
# it so the tags won't persist between tests. # it so the tags won't persist between tests.
@ -57,10 +57,10 @@ describe TemplateHelper do
end end
it "should issue a warning if the parameter types do not match the docstring in dispatch method" do 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" + expected_output_not_a_param = "[warn]: @param tag types do not match the" +
" code. The arg1 parameter is declared as types [\"Integer\"] in the " + " code. The arg1\n parameter is declared as types [\"Integer\"] in the " +
"docstring, but the code specifies the types [\"Optional[String]\"] " + "docstring,\n but the code specifies the types [\"Optional[String]\"]" +
"in file test near line 0\n" "\n in the file test near line 0.\n"
object = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet4xFunctions') object = PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject.new(:root, 'Puppet4xFunctions')
object.files = [['test', 0]] object.files = [['test', 0]]
object.type_info = [{ object.type_info = [{