From 5a283c2212fc1fc0d414257b86c2ac94fe1ce300 Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Thu, 22 Feb 2018 11:04:59 -0800 Subject: [PATCH] (maint) do not display name if there is nothing to display If there is a class, type, or function with no information documented but is pulled in by some fluke or tag we don't support, do not give it its own section --- lib/puppet-strings/markdown/base.rb | 11 +++++++++++ lib/puppet-strings/markdown/defined_types.rb | 3 ++- lib/puppet-strings/markdown/functions.rb | 3 ++- lib/puppet-strings/markdown/puppet_classes.rb | 3 ++- lib/puppet-strings/markdown/resource_types.rb | 3 ++- .../markdown/templates/classes_and_defines.erb | 2 ++ lib/puppet-strings/markdown/templates/function.erb | 2 ++ .../markdown/templates/resource_type.erb | 5 ++--- spec/fixtures/unit/markdown/output.md | 12 ++++++++++++ 9 files changed, 37 insertions(+), 7 deletions(-) diff --git a/lib/puppet-strings/markdown/base.rb b/lib/puppet-strings/markdown/base.rb index 8e9792a..ff3cedd 100644 --- a/lib/puppet-strings/markdown/base.rb +++ b/lib/puppet-strings/markdown/base.rb @@ -47,6 +47,9 @@ module PuppetStrings::Markdown # ") inherits foo::bar {\n" + # "}"} class Base + + DISPLAYED_TAGS = %w[summary see since version param raise option overload] + def initialize(registry, component_type) @type = component_type @registry = registry @@ -149,6 +152,14 @@ module PuppetStrings::Markdown end end + def contains_displayed_tags? + result = @registry[:docstring][:text] ? true : false + @tags.each do |tag| + result = true if DISPLAYED_TAGS.include? tag[:tag_name] + end + result + end + # @return [String] full markdown rendering of a component def render(template) file = File.join(File.dirname(__FILE__),"templates/#{template}") diff --git a/lib/puppet-strings/markdown/defined_types.rb b/lib/puppet-strings/markdown/defined_types.rb index e23c6a3..fc26eb4 100644 --- a/lib/puppet-strings/markdown/defined_types.rb +++ b/lib/puppet-strings/markdown/defined_types.rb @@ -11,7 +11,8 @@ module PuppetStrings::Markdown def self.render final = in_dtypes.length > 0 ? "## Defined types\n\n" : "" in_dtypes.each do |type| - final << PuppetStrings::Markdown::DefinedType.new(type).render + to_render = PuppetStrings::Markdown::DefinedType.new(type) + final << to_render.render if to_render.contains_displayed_tags? end final end diff --git a/lib/puppet-strings/markdown/functions.rb b/lib/puppet-strings/markdown/functions.rb index 1996938..c348318 100644 --- a/lib/puppet-strings/markdown/functions.rb +++ b/lib/puppet-strings/markdown/functions.rb @@ -11,7 +11,8 @@ module PuppetStrings::Markdown def self.render final = in_functions.length > 0 ? "## Functions\n\n" : "" in_functions.each do |func| - final << PuppetStrings::Markdown::Function.new(func).render + to_render = PuppetStrings::Markdown::Function.new(func) + final << to_render.render if to_render.contains_displayed_tags? end final end diff --git a/lib/puppet-strings/markdown/puppet_classes.rb b/lib/puppet-strings/markdown/puppet_classes.rb index 0818f9f..dbef9af 100644 --- a/lib/puppet-strings/markdown/puppet_classes.rb +++ b/lib/puppet-strings/markdown/puppet_classes.rb @@ -11,7 +11,8 @@ module PuppetStrings::Markdown def self.render final = in_classes.length > 0 ? "## Classes\n\n" : "" in_classes.each do |klass| - final << PuppetStrings::Markdown::PuppetClass.new(klass).render + to_render = PuppetStrings::Markdown::PuppetClass.new(klass) + final << to_render.render if to_render.contains_displayed_tags? end final end diff --git a/lib/puppet-strings/markdown/resource_types.rb b/lib/puppet-strings/markdown/resource_types.rb index 214a885..76e7777 100644 --- a/lib/puppet-strings/markdown/resource_types.rb +++ b/lib/puppet-strings/markdown/resource_types.rb @@ -11,7 +11,8 @@ module PuppetStrings::Markdown def self.render final = in_rtypes.length > 0 ? "## Resource types\n\n" : "" in_rtypes.each do |type| - final << PuppetStrings::Markdown::ResourceType.new(type).render + to_render = PuppetStrings::Markdown::ResourceType.new(type) + final << to_render.render if to_render.contains_displayed_tags? end final end diff --git a/lib/puppet-strings/markdown/templates/classes_and_defines.erb b/lib/puppet-strings/markdown/templates/classes_and_defines.erb index 8cf528c..580156a 100644 --- a/lib/puppet-strings/markdown/templates/classes_and_defines.erb +++ b/lib/puppet-strings/markdown/templates/classes_and_defines.erb @@ -1,5 +1,7 @@ ### <%= name %> +<%= text || summary || "The #{name} class." %> + <% if since -%> * **Since** <%= since %> diff --git a/lib/puppet-strings/markdown/templates/function.erb b/lib/puppet-strings/markdown/templates/function.erb index 40a6ca8..e1e3d22 100644 --- a/lib/puppet-strings/markdown/templates/function.erb +++ b/lib/puppet-strings/markdown/templates/function.erb @@ -1,6 +1,8 @@ ### <%= name %> Type: <%= type %> +<%= text || summary || "The #{name} function." %> + <% signatures.each do |sig| -%> #### `<%= sig.signature %>` diff --git a/lib/puppet-strings/markdown/templates/resource_type.erb b/lib/puppet-strings/markdown/templates/resource_type.erb index 12cff6f..8cf9487 100644 --- a/lib/puppet-strings/markdown/templates/resource_type.erb +++ b/lib/puppet-strings/markdown/templates/resource_type.erb @@ -1,5 +1,7 @@ ### <%= name %> +<%= text || summary || "The #{name} type." %> + <% if since -%> * **Since** <%= since %> @@ -12,9 +14,6 @@ <% end -%> <% end -%> -<% if text -%> -<%= text %> -<% end %> <% if examples -%> #### Examples <% examples.each do |eg| -%> diff --git a/spec/fixtures/unit/markdown/output.md b/spec/fixtures/unit/markdown/output.md index 005277d..e6bfc35 100644 --- a/spec/fixtures/unit/markdown/output.md +++ b/spec/fixtures/unit/markdown/output.md @@ -16,6 +16,8 @@ ### klass +An overview for a simple class. + * **Since** 1.0.0 * **See also** @@ -78,6 +80,8 @@ Default value: 'hi' ### klass::dt +An overview for a simple defined type. + * **Since** 1.1.0 * **See also** @@ -249,6 +253,8 @@ Default value: `false` ### func Type: Puppet Language +A simple Puppet function. + #### `func(Integer $param1, Any $param2, String $param3 = hi)` A simple Puppet function. @@ -283,6 +289,8 @@ Options: ### func3x Type: Ruby 3.x API +Documentation for an example 3.x function. + #### `func3x(String $param1, Integer $param2)` Documentation for an example 3.x function. @@ -304,6 +312,8 @@ The second parameter. ### func4x Type: Ruby 4.x API +An example 4.x function. + #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)` An overview for the first overload. @@ -354,6 +364,8 @@ The block parameter. ### func4x_1 Type: Ruby 4.x API +An example 4.x function with only one signature. + #### `func4x_1(Integer $param1)` An example 4.x function with only one signature.