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

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

Author: hunner

lib/puppet-strings/markdown/base.rb

@@ -127,7 +127,8 @@ def toc_info
       {
         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 @@ def value_string(value)
       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 DefinedTypes
 
     # @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 Functions
 
     # @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 PuppetClasses
 
     # @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 ResourceTypes
 
     # @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 -%>