From 1cdf7d41e963b9f49f9e90a7ba8b0295c44332fd Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Wed, 17 Dec 2014 16:39:56 -0800 Subject: [PATCH] (PDOC-17) Fix up parameter documentation Prior to this commit there were a few issues in the way information about parameters was collected. The previous implementation relied on parameters and their corresponding comments to be listed in the same order. Now the parameter is matched to the corresponding comment using the parameter name in the comment. Additionally, if a comment is present for a parameter that does not actually exist in the method it will appear as strike through in the HTML. --- .../definedtype/html/parameter_details.erb | 53 +++++++++++-------- .../templates/default/definedtype/setup.rb | 37 +++++++++++-- 2 files changed, 62 insertions(+), 28 deletions(-) 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 5f285a9..c27523b 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 @@ -3,30 +3,37 @@ 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 3b12f68..a138328 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb @@ -9,13 +9,10 @@ def parameter_details param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"} params = object.parameters + @param_details = [] - params.zip(param_tags).each do |param, tag| - description = tag.nil? ? nil : tag.text - param_types = tag.nil? ? nil : tag.types - @param_details.push({:name => param[0], :module => param[1], :desc => description, :types => param_types}) - end + @param_details = extract_param_details(params, param_tags) erb(:parameter_details) end @@ -39,3 +36,33 @@ def docstring erb(:docstring) end + +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], :module => 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.has_value?(tag.name) + param_exists = true + end + end + if !param_exists + parameter_info.push({:name => tag.name, :module => nil, :desc => tag.text, :types => tag.types, :exists? => false}) + end + end + + parameter_info +end