diff --git a/README.md b/README.md index 5cc9ffa..1f53e20 100644 --- a/README.md +++ b/README.md @@ -76,8 +76,6 @@ Here's an example of how you might document a 4x function: And here's an example of how you might document a class: - # Class: Example - # # This class is meant to serve as an example of how one might # want to document a manifest in a way that is compatible. # with the strings module diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb new file mode 100644 index 0000000..edebfa0 --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb @@ -0,0 +1,50 @@ +
+
+

<%= htmlify(@class_details[:desc]) %>

+
+
+
+ <% if @class_details[:examples] != {}%> +
+

Examples:

+ <% @class_details[:examples].each do |title, text| %> +

<%= title %>

+ 
<%= text %>
+ <% end %> +
+ <% end %> + <% if @class_details[:since] %> +

Since:

+ + <% end %> + <% if @class_details[:return] %> +

Return:

+ + <% end %> +
diff --git a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/header.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/header.erb new file mode 100644 index 0000000..74b3dba --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/header.erb @@ -0,0 +1,5 @@ +
+

+ <%= @header_text %> +

+
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 5daaa2b..b55a473 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 @@ -1,18 +1,41 @@ -

Parameter Summary(collapse)

- + 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 5d7e4d1..adc2778 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb @@ -1,10 +1,92 @@ include T('default/module') def init - sections :header, :box_info, :pre_docstring, T('docstring'), :parameter_details + sections :header, :box_info, :pre_docstring, :docstring, :parameter_details end def parameter_details return if object.parameters.empty? + + param_tags = object.tags.find_all{ |tag| tag.tag_name == "param"} + params = object.parameters + + @param_details = [] + + @param_details = extract_param_details(params, param_tags) + erb(:parameter_details) end + +def header + if object.type == :hostclass + @header_text = "Puppet Class: #{object.name}" + elsif object.type == :definedtype + @header_text = "Puppet Defined Type: #{object.name}" + else + @header_text = "#{object.name}" + end + + erb(:header) +end + +def docstring + 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} + + 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