Merge pull request #357 from puppetlabs/CONT-1193-finish_providers_implementation

Author: chelnak

lib/puppet-strings.rb

@@ -55,7 +55,7 @@ def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
 
     return unless options[:describe]
 
-    render_describe(options[:describe_types], options[:describe_list], options[:providers])
+    render_describe(options[:describe_types], options[:describe_list], options[:providers], options[:list_providers])
   end
 
   def self.puppet_5?
@@ -72,9 +72,9 @@ def self.render_markdown(path)
     PuppetStrings::Markdown.render(path)
   end
 
-  def self.render_describe(describe_types, list = false, providers = false)
+  def self.render_describe(describe_types, list = false, show_providers = true, list_providers = false)
     require 'puppet-strings/describe'
-    PuppetStrings::Describe.render(describe_types, list, providers)
+    PuppetStrings::Describe.render(describe_types, list, show_providers, list_providers)
   end
 
   # Runs the YARD documentation server.

lib/puppet-strings/describe.rb

@@ -7,31 +7,38 @@
 module PuppetStrings::Describe
   # Renders requested types or a summarized list in the current YARD registry to STDOUT.
   # @param [Array] describe_types The list of names of the types to be displayed.
-  # @param [bool] list Create the summarized list instead of describing each type.
-  # @param [bool] _providers Show details of the providers.
+  # @param [bool] list_types Create the summarized list instead of describing each type.
+  # @param [bool] show_type_providers Show details of the providers of a specified type.
+  # @param [bool] list_providers Create a summarized list of providers.
   # @return [void]
-  def self.render(describe_types = [], list = false, _providers = false)
+  def self.render(describe_types = [], list_types = false, show_type_providers = true, list_providers = false)
     document = {
       defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash),
-      resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash)
+      resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),
+      providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash)
     }
-
-    if list
+    # if --list flag passed, produce a summarized list of types
+    if list_types
       puts 'These are the types known to puppet:'
-      document[:resource_types].each { |t| list_one_type(t) }
-    else
-      document[:providers] = YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash)
+      document[:resource_types].each { |t| list_one(t) }
 
+    # if a type(s) has been passed, show the details of that type(s)
+    elsif describe_types
       type_names = {}
       describe_types.each { |name| type_names[name] = true }
 
       document[:resource_types].each do |t|
-        show_one_type(t) if type_names[t[:name].to_s]
+        show_one_type(t, show_type_providers) if type_names[t[:name].to_s]
       end
+
+    # if --providers flag passed, produce a summarized list of providers
+    elsif list_providers
+      puts 'These are the providers known to puppet:'
+      document[:providers].each { |t| list_one(t) }
     end
   end
 
-  def self.show_one_type(resource_type)
+  def self.show_one_type(resource_type, providers = true)
     puts format("\n%<name>s\n%<underscore>s", name: resource_type[:name], underscore: '=' * resource_type[:name].length)
     puts resource_type[:docstring][:text]
 
@@ -42,8 +49,10 @@ def self.show_one_type(resource_type)
 
     puts "\nParameters\n----------"
     combined_list.sort_by { |p| p[:name] }.each { |p| show_one_parameter(p) }
+    return unless providers
+
     puts "\nProviders\n---------"
-    # Show providers here - list or provide details
+    resource_type[:providers]&.sort_by { |p| p[:name] }&.each { |p| puts p[:name].to_s.ljust(15) }
   end
 
   def self.show_one_parameter(parameter)
@@ -53,14 +62,14 @@ def self.show_one_parameter(parameter)
     puts format('Requires features %<required_features>s.', required_features: parameter[:required_features]) unless parameter[:required_features].nil?
   end
 
-  def self.list_one_type(type)
+  def self.list_one(object)
     targetlength = 48
     shortento = targetlength - 4
-    contentstring = type[:docstring][:text]
+    contentstring = object[:docstring][:text]
     end_of_line = contentstring.index("\n")  # "." gives closer results to old describeb, but breaks for '.k5login'
     contentstring = contentstring[0..end_of_line] unless end_of_line.nil?
     contentstring = "#{contentstring[0..shortento]} ..." if contentstring.length > targetlength
 
-    puts "#{type[:name].to_s.ljust(15)} - #{contentstring}"
+    puts "#{object[:name].to_s.ljust(15)} - #{contentstring}"
   end
 end

lib/puppet-strings/yard/handlers/ruby/function_handler.rb

@@ -322,7 +322,7 @@ def add_param_tag(object, tags, name, file, line, type = nil, default = nil, opt
     end
 
     type ||= tag&.types ? tag.type : 'Any'
-    type = optional ? "Optional[#{type}]" : type
+    type = "Optional[#{type}]" if optional
 
     object.parameters << [name, to_puppet_literal(default)]
 

lib/puppet/face/strings.rb

@@ -3,7 +3,7 @@
 require 'puppet/face'
 
 # Implements the 'puppet strings' interface.
-Puppet::Face.define(:strings, '0.0.1') do
+Puppet::Face.define(:strings, '0.0.1') do # rubocop:disable Metrics/BlockLength
   summary 'Generate Puppet documentation with YARD.'
 
   action(:generate) do
@@ -83,7 +83,10 @@
       summary 'list types'
     end
     option '--providers' do
-      summary 'provide details on providers'
+      summary 'provide details on providers for each type'
+    end
+    option '--list-providers' do
+      summary 'list all providers'
     end
 
     # TODO: Implement the rest of describe behavior
@@ -96,6 +99,9 @@
     # * --list:
     #   List all types
 
+    # * --list-providers:
+    #   list all providers
+
     # * --meta:
     #   List all metaparameters
 
@@ -160,6 +166,8 @@ def build_generate_options(options = nil, *yard_args)
         generate_options[:describe] = true
         generate_options[:describe_types] = options[:describe_types]
         generate_options[:describe_list] = options[:list]
+        generate_options[:providers] = options[:providers]
+        generate_options[:list_providers] = options[:list_providers]
       end
 
       format = options[:format]