Merge pull request #157 from eputnam/pdoc-184_2

(maint) do not display name if there is nothing to display

lib/puppet-strings/markdown/base.rb

@@ -127,7 +127,8 @@ module PuppetStrings::Markdown
       {
         name: name.to_s,
         link: link,
-        desc: summary || @registry[:docstring][:text].gsub("\n", ". ")
+        desc: summary || @registry[:docstring][:text][0..140].gsub("\n",' '),
+        private: private?
       }
     end
 
@@ -149,6 +150,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
+
     # @return [String] full markdown rendering of a component
     def render(template)
       file = File.join(File.dirname(__FILE__),"templates/#{template}")

lib/puppet-strings/markdown/defined_types.rb

@@ -5,22 +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|
-        final << PuppetStrings::Markdown::DefinedType.new(type).render
+        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,22 +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|
-        final << PuppetStrings::Markdown::Function.new(func).render
+        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,22 +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|
-        final << PuppetStrings::Markdown::PuppetClass.new(klass).render
+        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,22 +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|
-        final << PuppetStrings::Markdown::ResourceType.new(type).render
+        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/classes_and_defines.erb

@@ -1,5 +1,15 @@
 ### <%= name %>
 
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} class." %>
+
+<% end -%>
 <% if since -%>
 * **Since** <%= since %>
 

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

@@ -1,6 +1,16 @@
 ### <%= name %>
 Type: <%= type %>
 
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} class." %>
+
+<% end -%>
 <% signatures.each do |sig| -%>
 #### `<%= sig.signature %>`
 

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

@@ -1,5 +1,15 @@
 ### <%= name %>
 
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} type." %>
+
+<% end -%>
 <% if since -%>
 * **Since** <%= since %>
 
@@ -12,9 +22,6 @@
 <% end -%>
 
 <% end -%>
-<% if text -%>
-<%= text %>
-<% end %>
 <% if examples -%>
 #### Examples
 <% examples.each do |eg| -%>

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,7 +1,10 @@
 # Reference
 
 ## Classes
+### Public Classes
 * [`klass`](#klass): A simple class.
+### Private Classes
+* `noparams`: Overview for class noparams
 ## Defined types
 * [`klass::dt`](#klassdt): A simple defined type.
 ## Resource types
@@ -16,6 +19,8 @@
 
 ### klass
 
+An overview for a simple class.
+
 * **Since** 1.0.0
 
 * **See also**
@@ -78,6 +83,8 @@ Default value: 'hi'
 
 ### klass::dt
 
+An overview for a simple defined type.
+
 * **Since** 1.1.0
 
 * **See also**
@@ -249,6 +256,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 +292,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 +315,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 +367,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.

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

@@ -5,6 +5,7 @@ describe PuppetStrings::Markdown::Base do
     before :each do
       YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
 # An overview
+# @api private
 # @summary A simple class.
 # @param param1 First param.
 # @param param2 Second param.
@@ -36,6 +37,12 @@ SOURCE
 
     end
 
+    describe '#private?' do
+      it do
+        expect(component.private?).to be true
+      end
+    end
+
     describe '#params' do
       it 'returns the expected params' do
         expect(component.params.size).to eq 3
@@ -114,13 +121,19 @@ 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
         expect(toc).to be_instance_of Hash
       end
       it 'uses overview for :desc in absence of summary' do
-        expect(toc[:desc]).to eq 'An overview. It\'s a longer overview. Ya know?'
+        expect(toc[:desc]).to eq 'An overview It\'s a longer overview Ya know?'
       end
     end
 

spec/unit/puppet-strings/markdown_spec.rb

@@ -35,6 +35,10 @@ class klass (
 ) inherits foo::bar {
 }
 
+# Overview for class noparams
+# @api private
+class noparams () {}
+
 # An overview for a simple defined type.
 # @summary A simple defined type.
 # @since 1.1.0