From de3c1e776d5ae870af033e00f2c76261f1db9851 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Mon, 17 Nov 2014 11:03:57 -0800 Subject: [PATCH 1/6] (PDOC-17) Add support for YARD tags in puppet code Prior to this commit, most of the HTML created for documenting puppet code was auto-generated by YARD, meaning that it was not always presented in a way that was consistent or easy to read. Now we are explicitly defining the HTML and styling that we want to use when generating documentation for defined types and classes. This means that we can define exactly how we want the output to look so that is more compatible with puppet code. --- .../default/definedtype/html/docstring.erb | 51 +++++++++++++++++++ .../definedtype/html/parameter_details.erb | 48 ++++++++++------- .../templates/default/definedtype/setup.rb | 33 +++++++++++- 3 files changed, 114 insertions(+), 18 deletions(-) create mode 100644 lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb 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..de09fc1 --- /dev/null +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb @@ -0,0 +1,51 @@ +

Class: <%= @class_details[:name] %>

+
+
+

<%= @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/parameter_details.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb index 5daaa2b..5f285a9 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,32 @@ -

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..3b12f68 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,41 @@ 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 = [] + + 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 + erb(:parameter_details) 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 From 1cdf7d41e963b9f49f9e90a7ba8b0295c44332fd Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Wed, 17 Dec 2014 16:39:56 -0800 Subject: [PATCH 2/6] (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 From d15269458e96d9a4c9eb01f9678d05a49a2c6523 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Thu, 18 Dec 2014 10:40:22 -0800 Subject: [PATCH 3/6] (PDOC-17) Add TBD for unspecified parameter types Prior to this commit if the type for a parameter was not specified in the comment, nothing would be printed. Since we'll soon be adding functionality which will determine the type programmatically, it made more since to leave a place holder rather than nothing at all. As such, the type is now listed as "TBD" if it is not specified by the user in the comment. --- .../definedtype/html/parameter_details.erb | 58 ++++++++++--------- 1 file changed, 30 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 c27523b..b5753d4 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 @@ -6,34 +6,36 @@ <% if !param[:exists?] %> <% end %> - <%= param[:name] %> - <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %> - <% if param[:types] %> - - ( <% param[:types].each do |type| %> - - <% if param[:types].last != type %> - <%= type %>, - <% else %> - <%= type %> - <% end %> - - <% end %>) - - <% end %> - <% unless param[:module].nil? %> - <%= "=> #{param[:module]}" %> - <% end %> - <% if param[:desc]%> - — -
-

<%= param[:desc] %>

-
- <% end %> - - <% if !param[:exists] %> - - <% end %> + <%= param[:name] %> + <%# TODO: Linkify defaults that resolve to variable declarations in a different scope. %> + + <% if param[:types] %> + (<% param[:types].each do |type| %> + + <% if param[:types].last != type %> + <%= type %>, + <% else %> + <%= type %> + <% end %> + + <% end %>) + <% else %> + (TBD) + <% end %> + + <% unless param[:module].nil? %> + <%= "=> #{param[:module]}" %> + <% end %> + <% if param[:desc]%> + — +
+

<%= param[:desc] %>

+
+ <% end %> + <% if !param[:exists] %> + + <% end %> + <% end %> From 1f2d9a2d8ac1b91d25d4bcf7f378892d9d31e944 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Thu, 18 Dec 2014 13:34:43 -0800 Subject: [PATCH 4/6] (PDOC-17) Clean up code and update README Do a bit of renaming and add some comments to make the processing of parameter details a bit more clear. Additionally, update the example in the README so that it will actually be parsed properly by YARD (since YARD does not expect the one line title before the description). --- README.md | 2 -- .../definedtype/html/parameter_details.erb | 4 ++-- .../templates/default/definedtype/setup.rb | 18 +++++++++++++++--- 3 files changed, 17 insertions(+), 7 deletions(-) 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/parameter_details.erb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/parameter_details.erb index b5753d4..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 @@ -23,8 +23,8 @@ (TBD) <% end %> - <% unless param[:module].nil? %> - <%= "=> #{param[:module]}" %> + <% unless param[:fq_name].nil? %> + <%= "=> #{param[:fq_name]}" %> <% end %> <% if param[:desc]%> — 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 a138328..9da3463 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb @@ -37,8 +37,20 @@ def docstring 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 actually exists and just not just defined in the comment def extract_param_details(params_hash, tags_hash) - parameter_info = [] # Extract the information for parameters that actually exist @@ -48,7 +60,7 @@ def extract_param_details(params_hash, tags_hash) 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}) + 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 @@ -60,7 +72,7 @@ def extract_param_details(params_hash, tags_hash) end end if !param_exists - parameter_info.push({:name => tag.name, :module => nil, :desc => tag.text, :types => tag.types, :exists? => false}) + parameter_info.push({:name => tag.name, :fq_name => nil, :desc => tag.text, :types => tag.types, :exists? => false}) end end From e85f58a64e521e7c5b7dc1778144ed3f1f631823 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Tue, 30 Dec 2014 15:19:00 -0800 Subject: [PATCH 5/6] (PDOC-17) Changed header and remove sub-header Prior to this commit there was a header and a sub-header for defined types and classes. This was a little redundant so rather than doing that, remove the sub-header and make the main header more readable. --- .../templates/default/definedtype/html/docstring.erb | 1 - .../templates/default/definedtype/html/header.erb | 5 +++++ .../yard/templates/default/definedtype/setup.rb | 12 ++++++++++++ 3 files changed, 17 insertions(+), 1 deletion(-) create mode 100644 lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/header.erb 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 index de09fc1..0f24670 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb @@ -1,4 +1,3 @@ -

Class: <%= @class_details[:name] %>

<%= @class_details[:desc] %>

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/setup.rb b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb index 9da3463..13f1033 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb @@ -17,6 +17,18 @@ def parameter_details 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" } From 1fae19e5aebffc1d643951b1a0570c5cd99acd19 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Mon, 5 Jan 2015 16:01:43 -0800 Subject: [PATCH 6/6] (PDOC-17) htmlify class/defined type descriptions Prior to this commit we were not calling htmlify on the docstring for the description of a puppet class on defined type. This meant that the raw string would be displayed without paying attention to any potential markdown or rdoc formatting present. Now the YARD method htmlify is being called on the docstring so that it will be displayed properly. Additionally clean up an unclear comment and fix a small bug in the way parameter information is processed. --- .../yard/templates/default/definedtype/html/docstring.erb | 2 +- .../strings/yard/templates/default/definedtype/setup.rb | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) 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 index 0f24670..edebfa0 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/html/docstring.erb @@ -1,6 +1,6 @@
-

<%= @class_details[:desc] %>

+

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

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 13f1033..adc2778 100644 --- a/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb +++ b/lib/puppetx/puppetlabs/strings/yard/templates/default/definedtype/setup.rb @@ -61,7 +61,7 @@ end # @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 actually exists and just not just defined 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 = [] @@ -79,7 +79,7 @@ def extract_param_details(params_hash, tags_hash) tags_hash.each do |tag| param_exists = false parameter_info.each do |parameter| - if parameter.has_value?(tag.name) + if parameter[:name] == tag.name param_exists = true end end