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 8ea5588..39ae076 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb @@ -1,22 +1,24 @@ 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 return if object.parameters.empty? - @html_helper = HTMLHelper.new - param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"} params = object.parameters @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 @@ -34,65 +36,8 @@ def header end def docstring - @html_helper = HTMLHelper.new - 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} + @class_details = @template_helper.extract_tag_data(object) 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 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 4cb0620..fed42cf 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb @@ -1,5 +1,8 @@ +# 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 = [] @@ -12,6 +15,7 @@ class HTMLHelper result.join end + # Generates the HTML to format the relevant data about parameters def generate_parameters(params) result = [] diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_details_list.erb similarity index 100% rename from lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb rename to lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_details_list.erb 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 84ee82f..66679ab 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/setup.rb @@ -1,6 +1,7 @@ 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'), @@ -8,6 +9,7 @@ def init :method_details_list, [T('method_details')] @methods = object.children + @template_helper = TemplateHelper.new end def header @@ -59,20 +61,8 @@ def method_details_list @html_helper = HTMLHelper.new @methods.each do |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 + method_info = @template_helper.extract_tag_data(object) param_details = nil if object['puppet_4x_function'] @@ -85,45 +75,13 @@ def method_details_list # Convert the matched string into an array of strings params = parameters.nil? ? nil : parameters[1].split(/\s*,\s*/) - param_details = extract_param_details(params, param_tags) + param_details = @template_helper.extract_param_details(params, param_tags) unless params.nil? end - @class_details.push({:name => object.name, :desc => object.docstring, :examples => examples, :since => since_text, :return => return_details, :params => param_details}) + method_info[:params] = param_details + + @class_details.push(method_info) end - erb(:docstring) + erb(:method_details_list) end - -def extract_param_details(params_array, tags_hash) - if params_array.nil? - return - end - - parameter_info = [] - - # Extract the information for parameters that actually exist - params_array.each do |param| - param_tag = tags_hash.find { |tag| tag.name == param } - - description = param_tag.nil? ? nil : param_tag.text - param_types = param_tag.nil? ? nil : param_tag.types - - parameter_info.push({:name => param, :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, :desc => tag.text, :types => tag.types, :exists? => false}) - end - end - - parameter_info -end - diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/template_helper.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/template_helper.rb new file mode 100644 index 0000000..1c1be34 --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/template_helper.rb @@ -0,0 +1,81 @@ +# 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 paramter 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 + def extract_param_details(parameters, tags_hash, fq_name = false) + parameter_info = [] + + + # Extract the information for parameters that actually exist + 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 +end