From 1cdf7d41e963b9f49f9e90a7ba8b0295c44332fd Mon Sep 17 00:00:00 2001
From: Hailee Kenney <hailee@puppetlabs.com>
Date: Wed, 17 Dec 2014 16:39:56 -0800
Subject: [PATCH] (PDOC-17) Fix up parameter documentation

Prior to this commit there were a few issues in the way information
about parameters was collected. The previous implementation relied
on parameters and their corresponding comments to be listed in the
same order. Now the parameter is matched to the corresponding comment
using the parameter name in the comment.

Additionally, if a comment is present for a parameter that does
not actually exist in the method it will appear as strike through
in the HTML.
---
 .../definedtype/html/parameter_details.erb    | 53 +++++++++++--------
 .../templates/default/definedtype/setup.rb    | 37 +++++++++++--
 2 files changed, 62 insertions(+), 28 deletions(-)

diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb
index 5f285a9..c27523b 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb
+++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb
@@ -3,30 +3,37 @@
   <ul class="param">
     <% @param_details.each do |param| %>
       <li>
-        <span class="name"><%= param[:name] %></span>
-        <% unless param[:module].nil? %>
-          <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
-          <% if param[:types] %>
-            <span class="type">
-              ( <%  param[:types].each do |type| %>
-                <tt>
-                  <%= type %>
-                  <% if param[:types].last != type %>
-                    ,
-                  <% end %>
-                </tt>
-              <% end %>)
-            </span>
-          <% end %>
-          <tt><%= "=> #{param[:module]}" %></tt>
+        <% if !param[:exists?] %>
+          <strike>
         <% end %>
-        <% if param[:desc]%>
-          —
-          <div class="inline">
-            <p><%=  param[:desc] %></p>
-          </div>
-        <% end %>
-      </li>
+         <span class="name"><%= param[:name] %></span>
+         <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
+         <% if param[:types] %>
+           <span class="type">
+             ( <%  param[:types].each do |type| %>
+               <tt>
+                 <% if param[:types].last != type %>
+                   <%= type %>,
+                 <% else %>
+                   <%= type %>
+                 <% end %>
+               </tt>
+             <% end %>)
+           </span>
+         <% end %>
+         <% unless param[:module].nil? %>
+           <tt><%= "=> #{param[:module]}" %></tt>
+         <% end %>
+         <% if param[:desc]%>
+           —
+           <div class="inline">
+             <p><%=  param[:desc] %></p>
+           </div>
+         <% end %>
+       </li>
+      <% if !param[:exists] %>
+        </strike>
+      <% end %>
     <% end %>
   </ul>
 </div>
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
index 3b12f68..a138328 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
+++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
@@ -9,13 +9,10 @@ def parameter_details
 
   param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
   params = object.parameters
+
   @param_details = []
 
-  params.zip(param_tags).each do |param, tag|
-    description = tag.nil? ? nil : tag.text
-    param_types = tag.nil? ? nil : tag.types
-    @param_details.push({:name => param[0], :module => param[1], :desc => description, :types => param_types})
-  end
+  @param_details = extract_param_details(params, param_tags)
 
   erb(:parameter_details)
 end
@@ -39,3 +36,33 @@ def docstring
 
   erb(:docstring)
 end
+
+def extract_param_details(params_hash, tags_hash)
+
+  parameter_info = []
+
+  # Extract the information for parameters that actually exist
+  params_hash.each do |param|
+    param_tag = tags_hash.find { |tag| tag.name == param[0] }
+
+    description = param_tag.nil? ? nil : param_tag.text
+    param_types = param_tag.nil? ? nil : param_tag.types
+
+    parameter_info.push({:name => param[0], :module => param[1], :desc => description, :types => param_types, :exists? => true})
+  end
+
+  # Check if there were any comments for parameters that do not exist
+  tags_hash.each do |tag|
+    param_exists = false
+    parameter_info.each do |parameter|
+      if parameter.has_value?(tag.name)
+        param_exists = true
+      end
+    end
+    if !param_exists
+      parameter_info.push({:name => tag.name, :module => nil, :desc => tag.text, :types => tag.types, :exists? => false})
+    end
+  end
+
+  parameter_info
+end