(PDOC-24) Clean up code for HTML generation

Prior to this commit there was a lot of duplicated code around
the generation of HTML for templates. Clean up and simplify code by
adding an HTMLHelper class with helper functions which can be used
in place of repeated logic.

lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb

@@ -27,23 +27,7 @@
     <p class="tag_title">Return:</p>
     <ul class="return">
       <li>
-        <span class ="type">
+        <%= @html_helper.generate_return_types(@class_details[:return][1], @class_details[:return][0]) %>
-          <% if !@class_details[:return][1].nil? %>
-            (<tt>
-              <% @class_details[:return][1].each do |type| %>
-                <%= type %>
-                <% if @class_details[:return][1].last != type %>
-                  ,
-                <% end %>
-              <% end %>
-            </tt>) —
-          <% end %>
-        </span>
-        <% if !@class_details[:return][0].nil? %>
-          <div class="inline">
-            <p><%= @class_details[:return][0] %></p>
-          </div>
-        <% end %>
       </li>
     </ul>
   <% end %>

lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb

@@ -1,41 +1,6 @@
 <h2>Parameter Summary</h2>
 <div class="tags">
   <ul class="param">
-    <% @param_details.each do |param| %>
+    <%= @html_helper.generate_parameters(@param_details) %>
-      <li>
-        <% if !param[:exists?] %>
-          <strike>
-        <% end %>
-          <span class="name"><%= param[:name] %></span>
-          <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
-            <span class="type">
-              <% if param[:types] %>
-                (<%  param[:types].each do |type| %>
-                  <tt>
-                    <% if param[:types].last != type %>
-                      <%= type %>,
-                    <% else %>
-                      <%= type %>
-                    <% end %>
-                  </tt>
-                <% end %>)
-              <% else %>
-                <tt>(TBD)</tt>
-              <% end %>
-            </span>
-          <% unless param[:fq_name].nil? %>
-            <tt><%= "=> #{param[:fq_name]}" %></tt>
-          <% end %>
-          <% if param[:desc]%>
-            —
-            <div class="inline">
-              <p><%=  param[:desc] %></p>
-            </div>
-          <% end %>
-        <% if !param[:exists] %>
-          </strike>
-        <% end %>
-      </li>
-    <% end %>
   </ul>
 </div>

lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb

@@ -1,5 +1,7 @@
 include T('default/module')
 
+require File.join(File.dirname(__FILE__),'../html_helper')
+
 def init
   sections :header, :box_info, :pre_docstring, :docstring, :parameter_details
 end
@@ -7,6 +9,8 @@ end
 def parameter_details
   return if object.parameters.empty?
 
+  @html_helper = HTMLHelper.new
+
   param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
   params = object.parameters
 
@@ -30,6 +34,8 @@ def header
 end
 
 def docstring
+  @html_helper = HTMLHelper.new
+
   examples = Hash.new
   example_tags = object.tags.find_all { |tag| tag.tag_name == "example" }
   example_tags.each do |example|

lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb

@@ -0,0 +1,53 @@
+class HTMLHelper
+
+  def generate_return_types(types, desc = nil)
+    result = []
+
+    result << "(<span class=\"type\"><tt>" << types.join(", ") << "</tt></span>)"
+
+    if !desc.nil?
+      result << "- <div class=\"inline\"><p>#{desc}</p></div>"
+    end
+
+    result.join
+  end
+
+  def generate_parameters(params)
+    result = []
+
+    params.each do |param|
+      result << "<li>"
+
+      if !param[:exists?]
+        result << "<strike>"
+      end
+
+      result << "<span class=\"name\">#{param[:name]} </span>"
+      result << "<span class=\"type\">"
+
+      if param[:types]
+        result << "(" << "<tt>" << param[:types].join(", ") << "</tt>" << ")"
+      else
+        result << "(<tt>TBD</tt>)"
+      end
+        result << "</span>"
+
+      # This is only relevant for manifests, not puppet functions
+      unless param[:fq_name].nil?
+        result << "<tt> => #{param[:fq_name]}</tt>"
+      end
+
+      if param[:desc]
+        result << "- <div class=\"inline\"><p> #{param[:desc]} </p></div>"
+      end
+
+      if !param[:exists?]
+        result << "</strike>"
+      end
+
+      result << "</li>"
+    end
+
+    result.join
+  end
+end

lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb

@@ -1,6 +1,12 @@
+<h2>Function Details</h2>
 <% @class_details.each do |func| %>
   <h3 class="signature" id = <%= "#{func[:name]}-instance_method" %>>
-    <strong><%= func[:name] %> </strong>
+    <strong>
+      <% if func[:return] %>
+        <%= @html_helper.generate_return_types(func[:return][1]) %>
+      <% end %>
+      <%= func[:name] %>
+    </strong>
   </h3>
   <div class="docstring">
     <div class="discussion">
@@ -31,23 +37,7 @@
       <p class="tag_title">Returns:</p>
       <ul class="return">
         <li>
-          <span class ="type">
+          <%= @html_helper.generate_return_types(func[:return][1], func[:return][0]) %>
-            <% if !func[:return][1].nil? %>
-              (<tt>
-                <% func[:return][1].each do |type| %>
-                  <%= type %>
-                  <% if func[:return][1].last != type %>
-                    ,
-                  <% end %>
-                <% end %>
-              </tt>) —
-            <% end %>
-          </span>
-          <% if !func[:return][0].nil? %>
-            <div class="inline">
-              <p><%= func[:return][0] %></p>
-            </div>
-          <% end %>
         </li>
       </ul>
     <% end %>
@@ -55,39 +45,7 @@
       <p class="tag_title">Parameters:</p>
       <div class="tags">
         <ul class="param">
-          <% func[:params].each do |param| %>
+          <%= @html_helper.generate_parameters(func[:params]) %>
-            <li>
-              <% if !param[:exists?] %>
-                <strike>
-              <% end %>
-              <span class="name"><%= param[:name] %></span>
-              <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
-              <span class="type">
-                <% if param[:types] %>
-                  (<%  param[:types].each do |type| %>
-                    <tt>
-                      <% if param[:types].last != type %>
-                        <%= type %>,
-                      <% else %>
-                        <%= type %>
-                      <% end %>
-                    </tt>
-                  <% end %>)
-                <% else %>
-                  <tt>(TBD)</tt>
-                <% end %>
-              </span>
-              <% if param[:desc]%>
-                —
-                <div class="inline">
-                  <p><%=  param[:desc] %></p>
-                </div>
-              <% end %>
-              <% if !param[:exists] %>
-                </strike>
-              <% end %>
-            </li>
-          <% end %>
         </ul>
       </div>
     <% end %>

lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb

@@ -4,18 +4,10 @@
     <li class = "private">
       <span class = "summary_signature">
       <a href =<%= "##{method[:name]}-instance_method"%>>
-        <span class ="type">
           <% if ! method[:return_types].nil? %>
-            (<tt>
+            <%= @html_helper.generate_return_types(method[:return_types]) %>
-              <% method[:return_types].each do |type| %>
-                <%= type %>
-                <% if method[:return_types].last != type %>
-                  ,
-                <% end %>
-              <% end %>
-            </tt>) —
           <% end %>
-        </span>
+        -
        <strong><%= method[:name] %></strong>
       </span>
     </li></a>

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

@@ -1,9 +1,11 @@
 include T('default/module')
 
+require File.join(File.dirname(__FILE__),'../html_helper')
+
 def init
   sections :header, :box_info, :pre_docstring, T('docstring'),
     :method_summary, [:item_summary],
-    :method_details_list, :method_details
+    :method_details_list, [T('method_details')]
 
   @methods = object.children
 end
@@ -34,6 +36,7 @@ end
 
 def method_summary
   @method_details = []
+  @html_helper = HTMLHelper.new
 
   @methods.each do |method|
     # If there are multiple sentences in the method description, only
@@ -51,8 +54,9 @@ def method_summary
   erb(:method_summary)
 end
 
-def method_details
+def method_details_list
   @class_details = []
+  @html_helper = HTMLHelper.new
 
   @methods.each do |object|
     examples = Hash.new
@@ -122,3 +126,4 @@ def extract_param_details(params_array, tags_hash)
 
   parameter_info
 end
+