From 49171c92b9fadc54dbe840e916b628645542490b Mon Sep 17 00:00:00 2001
From: Ian Kronquist <iankronquist@teleport.com>
Date: Wed, 24 Jun 2015 12:36:13 -0700
Subject: [PATCH] (PDOC-37) Warn if parameter names don't match docs

Print the name of the parameter, the file, and the line number to stderr if the
parameter name does not match the name specified in the docs.
In order for this to be useful we need to present the user with the file name
and line number of the relevant parameters. This information needs to be
extracted from the code object and passed to the extract_param_details method.
---
 .../yard/templates/default/definedtype/setup.rb   |  2 +-
 .../templates/default/puppetnamespace/setup.rb    |  2 +-
 .../yard/templates/default/template_helper.rb     | 15 +++++++++++----
 3 files changed, 13 insertions(+), 6 deletions(-)

diff --git a/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/setup.rb b/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
index 39ae076..31d54fd 100644
--- a/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
+++ b/lib/puppet_x/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
@@ -18,7 +18,7 @@ def parameter_details
 
   @param_details = []
 
-  @param_details = @template_helper.extract_param_details(params, param_tags, true)
+  @param_details = @template_helper.extract_param_details(params, param_tags, object.files, true)
 
   erb(:parameter_details)
 end
diff --git a/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb b/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb
index 054cee2..5238f64 100644
--- a/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb
+++ b/lib/puppet_x/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb
@@ -75,7 +75,7 @@ def method_details_list
       # Convert the matched string into an array of strings
       params = parameters.nil? ? nil :  parameters[1].split(/\s*,\s*/)
 
-      param_details = @template_helper.extract_param_details(params, param_tags) unless params.nil?
+      param_details = @template_helper.extract_param_details(params, param_tags, object.files) unless params.nil?
     else
       param_details = @template_helper.comment_only_param_details(param_tags)
     end
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 40cf94e..030fd8f 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
@@ -1,7 +1,8 @@
+require "puppet"
+
 # A class containing helper methods to aid in the extraction of relevant data
 # from comments and YARD tags
 class TemplateHelper
-
   # Extracts data from comments which include the supported YARD tags
   def extract_tag_data(object)
     examples = Hash.new
@@ -35,13 +36,12 @@ class TemplateHelper
   #    :desc    => [String] The description provided in the comment
   #    :types   => [Array] The parameter type(s) specified in the comment
   #    :exists  => [Boolean] True only if the parameter exists in the documented logic and not just in a comment}
-  def extract_param_details(parameters, tags_hash, fq_name = false)
+  def extract_param_details(parameters, tags_hash, locations, fq_name = false)
     parameter_info = []
 
-    # Extract the information for parameters that actually exist
+    # Extract the information for parameters that exist
     # as opposed to parameters that are defined only in the comments
     parameters.each do |param|
-
       if fq_name
         param_name = param[0]
         fully_qualified_name = param[1]
@@ -73,6 +73,13 @@ class TemplateHelper
       end
       if !param_exists
         parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => false})
+        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}"
+        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."
+        end
       end
     end