Merge pull request #22 from hkenney/issue/master/PDOC-24_add_basic_templates_for_functions

(PDOC-24) Add basic templates for functions

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,7 +1,13 @@
 include T('default/module')
 
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
 def init
   sections :header, :box_info, :pre_docstring, :docstring, :parameter_details
+
+  @template_helper = TemplateHelper.new
+  @html_helper = HTMLHelper.new
 end
 
 def parameter_details
@@ -12,7 +18,7 @@ def parameter_details
 
   @param_details = []
 
-  @param_details = extract_param_details(params, param_tags)
+  @param_details = @template_helper.extract_param_details(params, param_tags, true)
 
   erb(:parameter_details)
 end
@@ -30,63 +36,8 @@ def header
 end
 
 def docstring
-  examples = Hash.new
-  example_tags = object.tags.find_all { |tag| tag.tag_name == "example" }
-  example_tags.each do |example|
-    examples["#{example.name}"] = example.text
-  end
 
-  return_tag = object.tags.find { |tag| tag.tag_name == "return"}
+  @class_details = @template_helper.extract_tag_data(object)
-  return_text = return_tag.nil? ? nil : return_tag.text
-  return_types = return_tag.nil? ? nil : return_tag.types
-  return_details = (return_text.nil? && return_types.nil?) ? nil : [return_text, return_types]
-
-  since_tag = object.tags.find { |tag| tag.tag_name == "since"}
-  since_text = since_tag.nil? ? nil : since_tag.text
-
-  @class_details = {:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details}
 
   erb(:docstring)
 end
-
-# Given the parameter information and YARD param tags, extracts the
-# useful information and returns it as an array of hashes which can
-# be printed and formatted in the paramters_details erb file
-#
-# @param params_hash [Array] parameter details obtained programmatically
-# @param tags_hash [Array] parameter details obtained from comments
-#
-# @return [Hash] The relevant information about each parameter
-# @option opts [String] :name The name of the parameter
-# @option opts [String] :fq_name The fully qualified parameter name
-# @option opts [String] :desc The description provided in the comment
-# @options opts [Array] :types The parameter type(s) specified in the comment
-# @options opts [Boolean] :exists? True only if the parameter exists in the documented logic and not just in a comment
-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], :fq_name => 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[:name] == tag.name
-        param_exists = true
-      end
-    end
-    if !param_exists
-      parameter_info.push({:name => tag.name, :fq_name => nil, :desc => tag.text, :types => tag.types, :exists? => false})
-    end
-  end
-
-  parameter_info
-end

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

@@ -0,0 +1,68 @@
+# A class containing helper methods to aid the generation of HTML
+# given formatted data
+class HTMLHelper
+
+  # Generates the HTML to format the relevant data about return values
+  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
+
+  # Generates the HTML to format the relevant data about parameters
+  def generate_parameters(params)
+    result = []
+
+    params.each do |param|
+      result << "<li>"
+
+      # Parameters which are documented in the comments but not
+      # present in the code itself are given the strike through
+      # styling in order to show the reader that they do not actually
+      # exist
+      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>" << ")"
+      # Don't bother with TBD since 3x functions will never have type info per parameter.
+      # However if the user does want to list a type for some reason that is still supported,
+      # we just don't want to suggest that they need to
+      elsif !param[:puppet_3_func]
+        result << "(<tt>TBD</tt>)"
+      end
+
+      result << "</span>"
+
+      # This is only relevant for manifests, not puppet functions
+      # This is due to the fact that the scope of a parameter (as illustrated by
+      # by it's fully qualified name) is not relevant for the parameters in puppet
+      # functions, but may be for components of a manifest (i.e. classes)
+      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/box_info.erb

@@ -0,0 +1,11 @@
+<dl class="box">
+  <dt class="r1 last" style="height: 16px;">Defined in:</dt>
+  <dd class="r1 last">
+  <% @source_files.each do |file| %>
+    <em><%= file[0] %></em>:
+    <%= file[1] %>
+    <br/>
+  <% end %>
+  </dd>
+</dl>
+<div class ="clear"></div>

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

@@ -0,0 +1,5 @@
+<div class='module_header'>
+  <h1>
+    <%= @header_text %>
+  </h1>
+</div>

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

@@ -0,0 +1,53 @@
+<h2>Function Details</h2>
+<% @class_details.each do |func| %>
+  <h3 class="signature" id = <%= "#{func[:name]}-instance_method" %>>
+    <strong>
+      <% if func[:return] %>
+        <%= @html_helper.generate_return_types(func[:return][1]) %>
+      <% end %>
+      <%= func[:name] %>
+    </strong>
+  </h3>
+  <div class="docstring">
+    <div class="discussion">
+      <p><%= htmlify(func[:desc]) %></p>
+    </div>
+  </div>
+  <div class="tags">
+    <% if func[:examples] != {}%>
+      <div class="examples">
+        <p class="tag_title">Examples:</p>
+        <% func[:examples].each do |title, text| %>
+          <div class="inline"><p><%= title %></p></div>
+          <pre class="example code"><code><span><%= text %></span></code></pre>
+        <% end %>
+      </div>
+    <% end %>
+    <% if func[:since] %>
+      <p class="tag_title">Since:</p>
+      <ul class="since">
+        <li>
+          <div class="inline">
+            <p><%= func[:since] %></p>
+          </div>
+        </li>
+      </ul>
+    <% end %>
+    <% if func[:return] %>
+      <p class="tag_title">Returns:</p>
+      <ul class="return">
+        <li>
+          <%= @html_helper.generate_return_types(func[:return][1], func[:return][0]) %>
+        </li>
+      </ul>
+    <% end %>
+    <% if func[:params] != nil %>
+      <p class="tag_title">Parameters:</p>
+      <div class="tags">
+        <ul class="param">
+          <%= @html_helper.generate_parameters(func[:params]) %>
+        </ul>
+      </div>
+    <% end %>
+  </div>
+<% end %>

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

@@ -0,0 +1,20 @@
+<h2>Available Functions</h2>
+<ul class="summary">
+  <% @method_details.each do |method| %>
+    <li class = "private">
+      <span class = "summary_signature">
+      <a href =<%= "##{method[:name]}-instance_method"%>>
+          <% if ! method[:return_types].nil? %>
+            <%= @html_helper.generate_return_types(method[:return_types]) %>
+          <% end %>
+        -
+       <strong><%= method[:name] %></strong>
+      </span>
+    </li></a>
+    <span class = "summary_desc">
+      <div class = "inline">
+        <p><%= method[:short_desc] %></p>
+      </div>
+    </span>
+  <% end %>
+</ul>

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

@@ -1,7 +1,89 @@
 include T('default/module')
 
+require File.join(File.dirname(__FILE__),'../html_helper')
+require File.join(File.dirname(__FILE__),'../template_helper')
+
 def init
-  sections :header, :box_info, :pre_docstring, T('docstring'),
+  sections :header, :box_info,
     :method_summary, [:item_summary],
     :method_details_list, [T('method_details')]
+
+  @methods = object.children
+  @template_helper = TemplateHelper.new
+end
+
+def header
+  # The list is expected to only contain one type of function
+  if @methods[0]['puppet_4x_function']
+    @header_text = "Puppet 4 Functions"
+  else
+    @header_text = "Puppet 3 Functions"
+  end
+
+  erb(:header)
+end
+
+def box_info
+  @source_files = []
+
+  @methods.each do |method|
+    # extract the file name and line number for each method
+    file_name = method.files[0][0]
+    line_number = method.files[0][1]
+
+    @source_files.push([method.name, "#{file_name} (#{line_number})"])
+  end
+
+  erb(:box_info)
+end
+
+def method_summary
+  @method_details = []
+  @html_helper = HTMLHelper.new
+
+  @methods.each do |method|
+    # If there are multiple sentences in the method description, only
+    # use the first one for the summary. If the author did not include
+    # any periods in their summary, include the whole thing
+    first_sentence = method.docstring.match(/^(.*?)\./)
+    brief_summary = first_sentence ? first_sentence : method.docstring
+
+    return_tag = method.tags.find { |tag| tag.tag_name == "return"}
+    return_types = return_tag.nil? ? nil : return_tag.types
+
+    @method_details.push({:name => method.name, :short_desc => brief_summary, :return_types => return_types})
+  end
+
+  erb(:method_summary)
+end
+
+def method_details_list
+  @class_details = []
+  @html_helper = HTMLHelper.new
+
+  @methods.each do |object|
+
+    method_info = @template_helper.extract_tag_data(object)
+    param_details = nil
+    param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
+
+    if object['puppet_4x_function']
+      # Extract the source code
+      source_code = object.source
+      # Extract the parameters for the source code
+      parameters = source_code.match(/(?:def .*)\((.*?)\)/)
+      # 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?
+    else
+      param_details = @template_helper.comment_only_param_details(param_tags)
+    end
+
+    method_info[:params] = param_details
+
+    @class_details.push(method_info)
+  end
+
+  erb(:method_details_list)
 end

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

@@ -0,0 +1,107 @@
+# 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
+    example_tags = object.tags.find_all { |tag| tag.tag_name == "example" }
+    example_tags.each do |example|
+      examples["#{example.name}"] = example.text
+    end
+
+    return_tag = object.tags.find { |tag| tag.tag_name == "return"}
+    return_text = return_tag.nil? ? nil : return_tag.text
+    return_types = return_tag.nil? ? nil : return_tag.types
+    return_details = (return_text.nil? && return_types.nil?) ? nil : [return_text, return_types]
+
+    since_tag = object.tags.find { |tag| tag.tag_name == "since"}
+    since_text = since_tag.nil? ? nil : since_tag.text
+
+    {:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details}
+  end
+
+  # Given the parameter information and YARD param tags, extracts the
+  # useful information and returns it as an array of hashes which can
+  # be printed and formatted as HTML
+  #
+  # @param parameters [Array] parameter details obtained programmatically
+  # @param tags_hash [Array] parameter details obtained from comments
+  # @param fq_name [Boolean] does this parameter have a fully qualified name?
+  #
+  # @return [Hash] The relevant information about each parameter with the following keys/values:
+  #   {:name    => [String] The name of the parameter
+  #    :fq_name => [String] The fully qualified parameter name
+  #    :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)
+    parameter_info = []
+
+    # Extract the information for parameters that actually 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]
+      else
+        param_name = param
+      end
+
+      param_tag = tags_hash.find { |tag| tag.name == param_name }
+
+      description = param_tag.nil? ? nil : param_tag.text
+      param_types = param_tag.nil? ? nil : param_tag.types
+
+      param_details = {:name => param_name, :desc => description, :types => param_types, :exists? => true}
+
+      if fq_name
+        param_details[:fq_name] = fully_qualified_name
+      end
+
+      parameter_info.push(param_details)
+    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[:name] == tag.name
+          param_exists = true
+        end
+      end
+      if !param_exists
+        parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => false})
+      end
+    end
+
+    parameter_info
+  end
+
+  # Generates parameter information in situations where the information can only
+  # come from YARD tags in the comments, not from the code itself. For now the only
+  # use for this is 3x functions. In this case exists? will always be true since we
+  # cannot verify if the parameter exists in the code itself. We must trust the user
+  # to provide information in the comments that is accurate.
+  #
+  # @param param_tags [Array] parameter details obtained from comments
+  #
+  # @return [Hash] The relevant information about each parameter with the following keys/values:
+  #   {:name          => [String] The name of the parameter
+  #    :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
+  #    :puppet_3_func => [Boolean] Are these parameters for a puppet 3 function? (relevant in HTML generation)}
+  def comment_only_param_details(param_tags)
+    return if param_tags.empty?
+
+    parameter_info = []
+
+    param_tags.each do |tag|
+      parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => true, :puppet_3_func => true})
+    end
+
+    parameter_info
+  end
+end