From 1f2d9a2d8ac1b91d25d4bcf7f378892d9d31e944 Mon Sep 17 00:00:00 2001
From: Hailee Kenney <hailee@puppetlabs.com>
Date: Thu, 18 Dec 2014 13:34:43 -0800
Subject: [PATCH] (PDOC-17) Clean up code and update README

Do a bit of renaming and add some comments to make the processing
of parameter details a bit more clear. Additionally, update the
example in the README so that it will actually be parsed properly
by YARD (since YARD does not expect the one line title before the
description).
---
 README.md                                      |  2 --
 .../definedtype/html/parameter_details.erb     |  4 ++--
 .../templates/default/definedtype/setup.rb     | 18 +++++++++++++++---
 3 files changed, 17 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 5cc9ffa..1f53e20 100644
--- a/README.md
+++ b/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
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 b5753d4..b55a473 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
@@ -23,8 +23,8 @@
                 <tt>(TBD)</tt>
               <% end %>
             </span>
-          <% unless param[:module].nil? %>
-            <tt><%= "=> #{param[:module]}" %></tt>
+          <% unless param[:fq_name].nil? %>
+            <tt><%= "=> #{param[:fq_name]}" %></tt>
           <% end %>
           <% if param[:desc]%>
             —
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 a138328..9da3463 100644
--- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
+++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
@@ -37,8 +37,20 @@ def docstring
   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 actually exists and just not just defined in the comment
 def extract_param_details(params_hash, tags_hash)
-
   parameter_info = []
 
   # Extract the information for parameters that actually exist
@@ -48,7 +60,7 @@ def extract_param_details(params_hash, tags_hash)
     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})
+    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
@@ -60,7 +72,7 @@ def extract_param_details(params_hash, tags_hash)
       end
     end
     if !param_exists
-      parameter_info.push({:name => tag.name, :module => nil, :desc => tag.text, :types => tag.types, :exists? => false})
+      parameter_info.push({:name => tag.name, :fq_name => nil, :desc => tag.text, :types => tag.types, :exists? => false})
     end
   end