From 60b2802f0477ec7ffcda302b6e0e6d216d0eda0b Mon Sep 17 00:00:00 2001
From: Hailee Kenney <hailee@puppetlabs.com>
Date: Thu, 22 Jan 2015 15:21:01 -0800
Subject: [PATCH] (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.
---
 .../default/definedtype/html/docstring.erb    | 18 +-----
 .../definedtype/html/parameter_details.erb    | 37 +-----------
 .../templates/default/definedtype/setup.rb    |  6 ++
 .../yard/templates/default/html_helper.rb     | 53 ++++++++++++++++
 .../puppetnamespace/html/docstring.erb        | 60 +++----------------
 .../puppetnamespace/html/method_summary.erb   | 12 +---
 .../default/puppetnamespace/setup.rb          |  9 ++-
 7 files changed, 79 insertions(+), 116 deletions(-)
 create mode 100644 lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb

diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb
index edebfa0..900985f 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb
+++ b/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">
-          <% 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 %>
+        <%= @html_helper.generate_return_types(@class_details[:return][1], @class_details[:return][0]) %>
       </li>
     </ul>
   <% end %>
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 b55a473..a085ac0 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
@@ -1,41 +1,6 @@
 <h2>Parameter Summary</h2>
 <div class="tags">
   <ul class="param">
-    <% @param_details.each do |param| %>
-      <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 %>
+    <%= @html_helper.generate_parameters(@param_details) %>
   </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 adc2778..8ea5588 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
+++ b/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|
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb
new file mode 100644
index 0000000..4cb0620
--- /dev/null
+++ b/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
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb
index cb5110a..8050727 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb
+++ b/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">
-            <% 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 %>
+          <%= @html_helper.generate_return_types(func[:return][1], func[:return][0]) %>
         </li>
       </ul>
     <% end %>
@@ -55,39 +45,7 @@
       <p class="tag_title">Parameters:</p>
       <div class="tags">
         <ul class="param">
-          <% func[:params].each do |param| %>
-            <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 %>
+          <%= @html_helper.generate_parameters(func[:params]) %>
         </ul>
       </div>
     <% end %>
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb
index 6d61392..11ec619 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_summary.erb
+++ b/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>
-              <% method[:return_types].each do |type| %>
-                <%= type %>
-                <% if method[:return_types].last != type %>
-                  ,
-                <% end %>
-              <% end %>
-            </tt>) —
+            <%= @html_helper.generate_return_types(method[:return_types]) %>
           <% end %>
-        </span>
+        -
        <strong><%= method[:name] %></strong>
       </span>
     </li></a>
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb
index a310566..84ee82f 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb
+++ b/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
+