(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.

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>

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