Merge pull request #21 from hkenney/issue/master/PDOC-17_add_support_for_yard_tags

(PDOC-17) Add support for YARD tags in puppet code

README.md

@@ -76,8 +76,6 @@ Here's an example of how you might document a 4x function:
 
 And here's an example of how you might document a class:
 
-     # Class: Example
-     #
      # This class is meant to serve as an example of how one might
      # want to document a manifest in a way that is compatible.
      # with the strings module

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

@@ -0,0 +1,50 @@
+<div class="docstring">
+  <div class="discussion">
+    <p><%= htmlify(@class_details[:desc]) %></p>
+  </div>
+</div>
+<div class="tags">
+  <% if @class_details[:examples] != {}%>
+    <div class="examples">
+    <p class="tag_title">Examples:</p>
+    <% @class_details[: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 @class_details[:since] %>
+    <p class="tag_title">Since:</p>
+    <ul class="since">
+      <li>
+        <div class="inline">
+          <p><%= @class_details[:since] %></p>
+        </div>
+      </li>
+    </ul>
+  <% end %>
+  <% if @class_details[:return] %>
+    <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 %>
+      </li>
+    </ul>
+  <% end %>
+</div>

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

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

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

@@ -1,18 +1,41 @@
-<h2>Parameter Summary<small>(<a href="#" class="summary_toggle">collapse</a>)</small></h2>
-<ul class="summary">
-  <% object.parameters.each do |param| %>
-    <li>
-      <a href="#">
-        <span class="summary_signature">
-          -
-          <strong><%= h param[0] %></strong>
-          <% unless param[1].nil? %>
-            <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %>
-            => <%= h param[1] %>
+<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 %>
-        </span>
-        <%# TODO: Grab onto @param tags and insert text/type. %>
-      </a>
-    </li>
-  <% end %>
-</ul>
+          <% 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,10 +1,92 @@
 include T('default/module')
 
 def init
-  sections :header, :box_info, :pre_docstring, T('docstring'), :parameter_details
+  sections :header, :box_info, :pre_docstring, :docstring, :parameter_details
 end
 
 def parameter_details
   return if object.parameters.empty?
+
+  param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"}
+  params = object.parameters
+
+  @param_details = []
+
+  @param_details = extract_param_details(params, param_tags)
+
   erb(:parameter_details)
 end
+
+def header
+  if object.type == :hostclass
+    @header_text = "Puppet Class: #{object.name}"
+  elsif object.type == :definedtype
+    @header_text = "Puppet Defined Type: #{object.name}"
+  else
+    @header_text = "#{object.name}"
+  end
+
+  erb(: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"}
+  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