From 26945eacf344146483a36fcb2d2c7b175d320ee8 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Wed, 28 Jan 2015 15:10:28 -0800 Subject: [PATCH] (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. --- .../yard/templates/default/html_helper.rb | 15 ++++++++-- .../default/puppetnamespace/setup.rb | 5 ++-- .../yard/templates/default/template_helper.rb | 30 ++++++++++--------- 3 files changed, 32 insertions(+), 18 deletions(-) diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb index fed42cf..b9a4a58 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb @@ -22,6 +22,10 @@ class HTMLHelper params.each do |param| result << "
  • " + # 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 << "" end @@ -31,12 +35,19 @@ class HTMLHelper if param[:types] result << "(" << "" << param[:types].join(", ") << "" << ")" - 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 << "(TBD)" end - result << "" + + result << "" # 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 << " => #{param[:fq_name]}" end 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 3677e4a..054cee2 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb +++ b/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] diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/template_helper.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/template_helper.rb index bba88d9..40cf94e 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/template_helper.rb +++ b/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