Merge pull request #50 from iankronquist/choke-yard-warnings

(PDOC-38) Prevent warnings from being issued twice

lib/puppet_x/puppetlabs/strings/yard/monkey_patches.rb

@@ -31,4 +31,13 @@ class YARD::Logger
     return false unless level > INFO # no progress in verbose/debug modes
     @show_progress
   end
+
+  # Redirect Yard command line warnings to a log file called .yardwarns
+  # Yard warnings may be irrelevant, spurious, or may not conform with our
+  # styling and UX design. They are also printed on stdout by default.
+  def warn warning
+    f = File.new '.yardwarns', 'a'
+    f.write warning
+    f.close()
+  end
 end

lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/html/header.erb

@@ -0,0 +1,17 @@
+<h1>Method: <%= object.path %></h1>
+<div class="box_info">
+  <dl>
+    <dt class="">Defined in:</dt>
+    <dd class="">
+    <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+    <% end %>
+    </dd>
+  </dl>
+</div>
+
+<div class="method_details_list">
+  <div id="method_details">
+    <%= yieldall :index => 0 %>
+  </div>
+</div>

lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/setup.rb

@@ -0,0 +1,22 @@
+include T('default/module')
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
+def init
+  sections :header, [:method_signature, T('docstring'), :source]
+  parents = YARD::Registry.all(:method).reject do |item|
+    item.name == object.name and item.namespace === PuppetX::PuppetLabs::Strings::YARD::CodeObjects::PuppetNamespaceObject
+  end
+  if parents.length == 0
+require 'pry'; binding.pry
+    @template_helper = TemplateHelper.new
+    @template_helper.check_parameters_match_docs object
+  end
+end
+
+def source
+  return if owner != object.namespace
+  return if Tags::OverloadTag === object
+  return if object.source.nil?
+  erb(:source)
+end

lib/puppet_x/puppetlabs/strings/yard/templates/default/method_details/text/header.erb

@@ -0,0 +1,2 @@
+<%= yieldall %>
+

lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb

@@ -77,6 +77,7 @@ def method_details_list
 
       param_details = @template_helper.extract_param_details(params, param_tags) unless params.nil?
       @template_helper.check_types_match_docs object, param_details
+      @template_helper.check_parameters_match_docs object
     else
       param_details = @template_helper.comment_only_param_details(param_tags)
     end

lib/puppet_x/puppetlabs/strings/yard/templates/default/template_helper.rb

@@ -153,7 +153,7 @@ class TemplateHelper
                     "#{actual_types.inspect} Sorry, the file and line number could" +
                     "not be determined."
                 end
-                log.warn warning
+                $stderr.puts warning
               end
             end
           end

spec/unit/puppet_x/puppetlabs/strings/yard/examples/test-param-names-differ-with-dispatch/lib/test.rb

@@ -0,0 +1,18 @@
+# @param not_a_param [Integer] the first number to be compared
+# @param also_not_a_param [Integer] the second number to be compared
+Puppet::Functions.create_function(:max) do
+  dispatch max_1 do
+    param 'Integer[1,2]', :num_a
+    param 'Integer', :num_b
+  end
+  dispatch max_2 {
+    param 'String', :num_c
+    param 'String[1,2]', :num_d
+  }
+  def max_1(num_a, num_b)
+    num_a >= num_b ? num_a : num_b
+  end
+  def max_2(num_a, num_b)
+    num_a >= num_b ? num_a : num_b
+  end
+end

spec/unit/puppet_x/puppetlabs/strings/yard/examples/test-param-names-differ-with-types/lib/test.rb

@@ -0,0 +1,7 @@
+# @param not_a_param [Integer[1,2]] the first number to be compared
+# @param also_not_a_param [Integer[1,2]] 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

spec/unit/puppet_x/puppetlabs/strings/yard/examples/test-param-names-differ/lib/test.rb

@@ -0,0 +1,7 @@
+# @param not_a_param [Integer] the first number to be compared
+# @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

spec/unit/puppet_x/puppetlabs/strings/yard/examples/test-param-names-match-with-dispatch/lib/test.rb

@@ -0,0 +1,11 @@
+# @param [Integer] num_a the first number to be compared
+# @param num_b [Integer] the second number to be compared
+Puppet::Functions.create_function(:max) do
+  dispatch max_1 do
+    param 'Integer', :num_a
+    param 'Integer', :num_b
+  end
+  def max_1(num_a, num_b)
+    num_a >= num_b ? num_a : num_b
+  end
+end

spec/unit/puppet_x/puppetlabs/strings/yard/examples/test-param-names-match-with-types/lib/test.rb

@@ -0,0 +1,7 @@
+# @param num_a [Integer[1,2]] the first number to be compared
+# @param num_b [Integer[1,2]] 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

spec/unit/puppet_x/puppetlabs/strings/yard/examples/test-param-names-match/lib/test.rb

@@ -0,0 +1,7 @@
+# @param num_a [Integer] the first number to be compared
+# @param num_b [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

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

@@ -67,8 +67,7 @@ describe PuppetX::PuppetLabs::Strings::YARD::Handlers::HostClassHandler do
     # puppet. `expected` is the output expected from the stable branch. The
     # output from the master branch will use this instead:
     # "...specifies the types [String] in file..."
-    expected = <<-output
+    expected_stout = <<-output
-[warn]: @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
 Files:           1
 Modules:         0 (    0 undocumented)
 Classes:         0 (    0 undocumented)
@@ -78,12 +77,15 @@ Puppet Classes:     1 (    0 undocumented)
 Puppet Types:     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"
 
     expect {
+      expect {
         PuppetModuleHelper.using_module(File.dirname(__FILE__),'test') do |tmp|
           Dir.chdir('test')
           Puppet::Face[:strings, :current].yardoc
         end
-    }.to output(expected).to_stdout_from_any_process
+      }.to output(expected_stderr).to_stderr_from_any_process
+    }.to output(expected_stout).to_stdout_from_any_process
   end
 end

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

@@ -1,5 +1,7 @@
 require 'spec_helper'
+require 'lib/strings_spec/module_helper'
 require 'puppet_x/puppetlabs/strings/yard/handlers/puppet_4x_function_handler'
+require 'puppet/face/strings'
 require 'strings_spec/parsing'
 
 describe PuppetX::PuppetLabs::Strings::YARD::Handlers::Puppet4xFunctionHandler do
@@ -55,123 +57,82 @@ 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]: @param tag has unknown parameter" +
+      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"
-        " name: not_a_param \n    in file `(stdin)' 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]: @param tag has unknown " +
-        "parameter name: also_not_a_param \n    in file `(stdin)' near line 3"
       expect {
-        parse <<-RUBY
+        expect {
-          # @param not_a_param [Integer] the first number to be compared
+          PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ') do |tmp|
-          # @param also_not_a_param [Integer] the second number to be compared
+            Dir.chdir('test-param-names-differ')
-          Puppet::Functions.create_function(:max) do
+            Puppet::Face[:strings, :current].yardoc
-            def max(num_a, num_b)
-              num_a >= num_b ? num_a : num_b
-            end
           end
-        RUBY
+        }.to output(/documented/).to_stdout_from_any_process
-      }.to output("#{expected_output_not_a_param}\n#{expected_output_also_not_a_param}\n").to_stdout_from_any_process
+      }.to output("#{expected_output_not_a_param}\n#{expected_output_also_not_a_param}\n").to_stderr_from_any_process
   end
 
   it "should not issue a warning when the parameter names match the docstring" do
+      expected = ""
       expect {
-        parse <<-RUBY
+        expect {
-          # @param num_a [Integer] the first number to be compared
+          PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-match') do |tmp|
-          # @param num_b [Integer] the second number to be compared
+            Dir.chdir('test-param-names-match')
-          Puppet::Functions.create_function(:max) do
+            Puppet::Face[:strings, :current].yardoc
-            def max(num_a, num_b)
-              num_a >= num_b ? num_a : num_b
-            end
           end
-        RUBY
+        }.to output(/documented/).to_stdout_from_any_process
-      }.to output("").to_stdout_from_any_process
+      }.to output(expected).to_stderr_from_any_process
-  end
 
+  end
   it "should not issue a warning when there are parametarized types and parameter names are the same" do
+      expected = ""
       expect {
-        parse <<-RUBY
+        expect {
-          # @param num_a Integer[1,2] the first number to be compared
+          PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-match-with-types') do |tmp|
-          # @param num_b Integer[1,2] the second number to be compared
+            Dir.chdir('test-param-names-match-with-types')
-          Puppet::Functions.create_function(:max) do
+            Puppet::Face[:strings, :current].yardoc
-            def max(num_a, num_b)
-              num_a >= num_b ? num_a : num_b
-            end
           end
-        RUBY
+        }.to output(/documented/).to_stdout_from_any_process
-      }.to output("").to_stdout_from_any_process
+      }.to output(expected).to_stderr_from_any_process
   end
 
   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"
       expect {
-        parse <<-RUBY
+        expect {
-          # @param not_num_a Integer[1,2] the first number to be compared
+          PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ-with-types') do |tmp|
-          # @param num_b Integer[1,2] the second number to be compared
+            Dir.chdir('test-param-names-differ-with-types')
-          Puppet::Functions.create_function(:max) do
+            Puppet::Face[:strings, :current].yardoc
-            dispatch max_1 do
-              param 'Integer[1,2]', :num_a
-              param 'Integer[1,2]', :num_b
-            end
-
-            def max_1(num_a, num_b)
-              num_a >= num_b ? num_a : num_b
-            end
           end
-        RUBY
+        }.to output(/documented/).to_stdout_from_any_process
-      }.to output("#{expected_output_not_num_a}\n").to_stdout_from_any_process
+      }.to output("#{expected_output_not_a_param}\n#{expected_output_also_not_a_param}\n").to_stderr_from_any_process
   end
 
 
   it "should issue a warning if the parameter names do not match the docstring in dispatch method" do
-      expected_output_not_a_param = "[warn]: @param tag has unknown parameter" +
+      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"
-        " name: not_a_param \n    in file `(stdin)' 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]: @param tag has unknown " +
-        "parameter name: also_not_a_param \n    in file `(stdin)' near line 3"
       expect {
-        parse <<-RUBY
+        expect {
-          # @param not_a_param [Integer] the first number to be compared
+          PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-differ-with-dispatch') do |tmp|
-          # @param also_not_a_param [Integer] the second number to be compared
+            Dir.chdir('test-param-names-differ-with-dispatch')
-          Puppet::Functions.create_function(:max) do
+            Puppet::Face[:strings, :current].yardoc
-            dispatch max_1 do
-              param 'Integer[1,2]', :num_a
-              param 'Integer', :num_b
-            end
-
-            dispatch max_2 {
-              param 'String', :num_c
-              param 'String[1,2]', :num_d
-            }
-
-            def max_1(num_a, num_b)
-              num_a >= num_b ? num_a : num_b
-            end
-
-            def max_2(num_a, num_b)
-              num_a >= num_b ? num_a : num_b
-            end
           end
-        RUBY
+        }.to output(/documented/).to_stdout_from_any_process
-      }.to output("#{expected_output_not_a_param}\n#{expected_output_also_not_a_param}\n").to_stdout_from_any_process
+      }.to output("#{expected_output_not_a_param}\n#{expected_output_also_not_a_param}\n").to_stderr_from_any_process
   end
 
   it "should not issue a warning if the parameter names do match the " +
         "docstring in dispatch method" do
+      expected = ""
       expect {
-        parse <<-RUBY
+        expect {
-          # @param [Integer] num_a the first number to be compared
+          PuppetModuleHelper.using_module(File.dirname(__FILE__),'test-param-names-match-with-dispatch') do |tmp|
-          # @param num_b [Integer] the second number to be compared
+            Dir.chdir('test-param-names-match-with-dispatch')
-          Puppet::Functions.create_function(:max) do
+            Puppet::Face[:strings, :current].yardoc
-            dispatch max_1 do
-              param 'Integer', :num_a
-              param 'Integer', :num_b
-            end
-
-            def max_1(num_a, num_b)
-              num_a >= num_b ? num_a : num_b
-            end
           end
-        RUBY
+        }.to output(/documented/).to_stdout_from_any_process
-      }.to output("").to_stdout_from_any_process
+      }.to output(expected).to_stderr_from_any_process
   end
 
   it "should parse unusually named functions" do

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

@@ -57,7 +57,7 @@ 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 = "[warn]: @param tag types do not match the" +
+    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"
@@ -78,7 +78,7 @@ describe TemplateHelper do
     template_helper = TemplateHelper.new
     expect {
       template_helper.check_types_match_docs(object, param_details)
-    }.to output(expected_output_not_a_param).to_stdout_from_any_process
+    }.to output(expected_output_not_a_param).to_stderr_from_any_process
   end
 
   it "should not issue a warning if the parameter types do match the docstring in dispatch method" do
@@ -99,7 +99,7 @@ describe TemplateHelper do
     template_helper = TemplateHelper.new
     expect {
       template_helper.check_types_match_docs(object, param_details)
-    }.to output("").to_stdout_from_any_process
+    }.to output("").to_stderr_from_any_process
   end
 
   it "should not issue a warning if the types in  the docstring in dispatch method are assignable to parameter types" do
@@ -120,6 +120,6 @@ describe TemplateHelper do
     template_helper = TemplateHelper.new
     expect {
       template_helper.check_types_match_docs(object, param_details)
-    }.to output("").to_stdout_from_any_process
+    }.to output("").to_stderr_from_any_process
   end
 end