kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

(PDOC-24) Create helper class for templates 

Prior to this commit some of the logic used to extract data from
comments for templates was duplicated and a little messy. Create
the TemplateHelper class so that can be simplified and cleaned up
to make things more readable and efficient.
This commit is contained in:
Hailee Kenney 2015-01-22 22:26:58 -08:00
parent 60b2802f04
commit b9da8b164f
5 changed files with 99 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb
View File

@ -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

4
lib/puppetx/puppetlabs/strings/yard/templates/default/html_helper.rb
View File

@ -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 = []

0
lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/docstring.erb → lib/puppetx/puppetlabs/strings/yard/templates/default/puppetnamespace/html/method_details_list.erb
View File

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

@ -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

81
lib/puppetx/puppetlabs/strings/yard/templates/default/template_helper.rb Normal file
View File

@ -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