(maint) update table of contents

The table_of_contents template was already too bulky and redundant and recognizing public and private components was only going to make it worse. This refactors the toc template and the toc class to use a generic outline for all components.

lib/puppet-strings/markdown/base.rb

@@ -130,7 +130,8 @@ module PuppetStrings::Markdown
       {
         name: name.to_s,
         link: link,
-        desc: summary || @registry[:docstring][:text].gsub("\n", ". ")
+        desc: summary || @registry[:docstring][:text].gsub("\n", ". "),
+        private: private?
       }
     end
 
@@ -152,6 +153,15 @@ module PuppetStrings::Markdown
       end
     end
 
+    def private?
+      result = false
+      api = @tags.find { |tag| tag[:tag_name] == 'api' }
+      unless api.nil?
+        result = api[:text] == 'private' ? true : false
+      end
+      result
+    end
+
     def contains_displayed_tags?
       result = @registry[:docstring][:text] ? true : false
       @tags.each do |tag|

lib/puppet-strings/markdown/defined_types.rb

@@ -5,23 +5,30 @@ module PuppetStrings::Markdown
 
     # @return [Array] list of defined types
     def self.in_dtypes
-      YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash)
+      arr = YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::DefinedType.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_dtypes.nil?
+        in_dtypes.find { |type| type.private? }.nil? ? false : true
+      end
     end
 
     def self.render
       final = in_dtypes.length > 0 ? "## Defined types\n\n" : ""
       in_dtypes.each do |type|
-        to_render = PuppetStrings::Markdown::DefinedType.new(type)
-        final << to_render.render if to_render.contains_displayed_tags?
+        final << type.render unless type.private?
       end
       final
     end
 
     def self.toc_info
-      final = []
+      final = ["Defined types"]
 
       in_dtypes.each do |type|
-        final.push(PuppetStrings::Markdown::DefinedType.new(type).toc_info)
+        final.push(type.toc_info)
       end
 
       final

lib/puppet-strings/markdown/functions.rb

@@ -5,23 +5,30 @@ module PuppetStrings::Markdown
 
     # @return [Array] list of functions
     def self.in_functions
-      YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash)
+      arr = YARD::Registry.all(:puppet_function).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::Function.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_functions.nil?
+        in_functions.find { |func| func.private? }.nil? ? false : true
+      end
     end
 
     def self.render
       final = in_functions.length > 0 ? "## Functions\n\n" : ""
       in_functions.each do |func|
-        to_render = PuppetStrings::Markdown::Function.new(func)
-        final << to_render.render if to_render.contains_displayed_tags?
+        final << func.render unless func.private?
       end
       final
     end
 
     def self.toc_info
-      final = []
+      final = ["Functions"]
 
       in_functions.each do |func|
-        final.push(PuppetStrings::Markdown::Function.new(func).toc_info)
+        final.push(func.toc_info)
       end
 
       final

lib/puppet-strings/markdown/puppet_classes.rb

@@ -5,23 +5,30 @@ module PuppetStrings::Markdown
 
     # @return [Array] list of classes
     def self.in_classes
-      YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)
+      arr = YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::PuppetClass.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_classes.nil?
+        in_classes.find { |klass| klass.private? }.nil? ? false : true
+      end
     end
 
     def self.render
       final = in_classes.length > 0 ? "## Classes\n\n" : ""
       in_classes.each do |klass|
-        to_render = PuppetStrings::Markdown::PuppetClass.new(klass)
-        final << to_render.render if to_render.contains_displayed_tags?
+        final << klass.render unless klass.private?
       end
       final
     end
 
     def self.toc_info
-      final = []
+      final = ["Classes"]
 
       in_classes.each do |klass|
-        final.push(PuppetStrings::Markdown::PuppetClass.new(klass).toc_info)
+        final.push(klass.toc_info)
       end
 
       final

lib/puppet-strings/markdown/resource_types.rb

@@ -5,23 +5,30 @@ module PuppetStrings::Markdown
 
     # @return [Array] list of resource types
     def self.in_rtypes
-      YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash)
+      arr = YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash)
+      arr.map! { |a| PuppetStrings::Markdown::ResourceType.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_rtypes.nil?
+        in_rtypes.find { |type| type.private? }.nil? ? false : true
+      end
     end
 
     def self.render
       final = in_rtypes.length > 0 ? "## Resource types\n\n" : ""
       in_rtypes.each do |type|
-        to_render = PuppetStrings::Markdown::ResourceType.new(type)
-        final << to_render.render if to_render.contains_displayed_tags?
+        final << type.render unless type.private?
       end
       final
     end
 
     def self.toc_info
-      final = []
+      final = ["Resource types"]
 
       in_rtypes.each do |type|
-        final.push(PuppetStrings::Markdown::ResourceType.new(type).toc_info)
+        final.push(type.toc_info)
       end
 
       final

lib/puppet-strings/markdown/table_of_contents.rb

@@ -1,13 +1,21 @@
 module PuppetStrings::Markdown
   module TableOfContents
     def self.render
-      puppet_classes = PuppetStrings::Markdown::PuppetClasses.toc_info
-      puppet_defined_types = PuppetStrings::Markdown::DefinedTypes.toc_info
-      puppet_resource_types = PuppetStrings::Markdown::ResourceTypes.toc_info
-      puppet_functions = PuppetStrings::Markdown::Functions.toc_info
+      final = ""
 
-      template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb")
-      ERB.new(File.read(template), nil, '-').result(binding)
+      [PuppetStrings::Markdown::PuppetClasses,
+      PuppetStrings::Markdown::DefinedTypes,
+      PuppetStrings::Markdown::ResourceTypes,
+      PuppetStrings::Markdown::Functions].each do |r|
+        toc = r.toc_info
+        group_name = toc.shift
+        group = toc
+        priv = r.contains_private?
+
+        template = File.join(File.dirname(__FILE__),"templates/table_of_contents.erb")
+        final << ERB.new(File.read(template), nil, '-').result(binding)
+      end
+      final
     end
   end
 end

lib/puppet-strings/markdown/templates/table_of_contents.erb

@@ -1,24 +1,21 @@
-<% if puppet_classes.length > 0 -%>
-## Classes
-<% puppet_classes.each do |klassy| -%>
-* [`<%= klassy[:name] %>`](#<%= klassy[:link] %>): <%= klassy[:desc] %>
+<% if group.length > 0 -%>
+## <%= group_name %>
+<% if priv -%>
+### Public <%= group_name %>
+<% group.each do |item| -%>
+<% unless item[:private] -%>
+* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
 <% end -%>
 <% end -%>
-<% if puppet_defined_types.length > 0 -%>
-## Defined types
-<% puppet_defined_types.each do |dtype| -%>
-* [`<%= dtype[:name] %>`](#<%= dtype[:link] %>): <%= dtype[:desc] %>
+### Private <%= group_name %>
+<% group.each do |item| -%>
+<% if item[:private] -%>
+* `<%= item[:name] %>`: <%= item[:desc] %>
 <% end -%>
 <% end -%>
-<% if puppet_resource_types.length > 0 -%>
-## Resource types
-<% puppet_resource_types.each do |rtype| -%>
-* [`<%= rtype[:name] %>`](#<%= rtype[:link] %>): <%= rtype[:desc] %>
+<% else -%>
+<% group.each do |item| -%>
+* [`<%= item[:name] %>`](#<%= item[:link] %>): <%= item[:desc] %>
 <% end -%>
 <% end -%>
-<% if puppet_functions.length > 0 -%>
-## Functions
-<% puppet_functions.each do |func| -%>
-* [`<%= func[:name] %>`](#<%= func[:link] %>): <%= func[:desc] %>
-<% end -%>
 <% end -%>

spec/fixtures/unit/markdown/output.md

@@ -1,9 +1,10 @@
 # Reference
 
 ## Classes
+### Public Classes
 * [`klass`](#klass): A simple class.
-* [`noparams`](#noparams): Overview for class noparams
-* [`noparams_desc`](#noparams_desc): 
+### Private Classes
+* `noparams`: Overview for class noparams
 ## Defined types
 * [`klass::dt`](#klassdt): A simple defined type.
 ## Resource types
@@ -78,16 +79,6 @@ Third param.
 Default value: 'hi'
 
 
-### noparams
-
-Overview for class noparams
-
-
-### noparams_desc
-
-The noparams_desc class.
-
-
 ## Defined types
 
 ### klass::dt

spec/unit/puppet-strings/markdown/base_spec.rb

@@ -114,6 +114,12 @@ SOURCE
       end
     end
 
+    describe '#private?' do
+      it do
+        expect(component.private?).to be false
+      end
+    end
+
     describe '#toc_info' do
       let(:toc) { component.toc_info }
       it 'returns a hash' do

spec/unit/puppet-strings/markdown_spec.rb

@@ -36,10 +36,9 @@ class klass (
 }
 
 # Overview for class noparams
+# @api private
 class noparams () {}
 
-class noparams_desc () {}
-
 # An overview for a simple defined type.
 # @summary A simple defined type.
 # @since 1.1.0