(PDOC-24) Fix comments and remove unneeded sections

Prior to this commit, some of the comments in the code were not as
clear as they should have been and in some places comments were not
present where they were needed. Clean up existing comments and
add some for sections of code that are not very clear.

Additionally, some sections of the template for puppet namespaces
didn't really make sense to include, especially since we want the source
of truth for documentation of 3x functions to be the :doc string which is
passed in (not the comment block above the function). Thus, remove some of
the unneeded sections from the puppet namespace template.

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

@@ -22,6 +22,10 @@ class HTMLHelper
     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
@@ -31,12 +35,19 @@ class HTMLHelper
 
       if param[:types]
         result << "(" << "<tt>" << param[:types].join(", ") << "</tt>" << ")"
-      else
+      # 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>"
+
+      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

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

@@ -4,7 +4,7 @@ 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')]
 
@@ -13,6 +13,7 @@ def init
 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
@@ -26,7 +27,7 @@ def box_info
   @source_files = []
 
   @methods.each do |method|
-   # extract the file name and line number for each method
+    # extract the file name and line number for each method
     file_name = method.files[0][0]
     line_number = method.files[0][1]
 

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

@@ -27,18 +27,19 @@ class TemplateHelper
   #
   # @param parameters [Array] parameter details obtained programmatically
   # @param tags_hash [Array] parameter details obtained from comments
-  # @param fq_name [Boolean] does this paramter have a fully qualified name?
+  # @param fq_name [Boolean] does this parameter have a fully qualified name?
   #
-  # @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
+  # @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
@@ -81,23 +82,24 @@ class TemplateHelper
   # 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 paramter exists in the code itself. We must trust the user
+  # 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
-  # @option opts [String] :name The name of the parameter
-  # @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
+  # @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})
+      parameter_info.push({:name => tag.name, :desc => tag.text, :types => tag.types, :exists? => true, :puppet_3_func => true})
     end
 
     parameter_info