puppet-strings 3.0.0 → 4.0.0.rc.1

data/lib/puppet-strings/markdown/base.rb

@@ -20,6 +20,7 @@ module PuppetStrings::Markdown
   #    [{:tag_name=>"summary", :text=>"A simple class."},
   #     {:tag_name=>"since", :text=>"1.0.0"},
   #     {:tag_name=>"see", :name=>"www.puppet.com"},
+  #     {:tag_name=>"deprecated", :text=>"No longer supported and will be removed in a future release"},
   #     {:tag_name=>"example",
   #      :text=>
   #       "class { 'klass':\n" +
@@ -93,7 +94,8 @@ module PuppetStrings::Markdown
       since: 'since',
       summary: 'summary',
       note: 'note',
-      todo: 'todo' }.each do |method_name, tag_name|
+      todo: 'todo',
+      deprecated: 'deprecated' }.each do |method_name, tag_name|
       # @return [String] unless the tag is nil or the string.empty?
       define_method method_name do
         @tags.find { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }[:text] if @tags.any? { |tag| tag[:tag_name] == tag_name && !tag[:text].empty? }
@@ -159,7 +161,7 @@ module PuppetStrings::Markdown
     # @return [Array] option tag hashes that have a parent parameter_name
     def options_for_param(parameter_name)
       opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
-      opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
+      opts_for_p unless opts_for_p.nil? || opts_for_p.empty?
     end
 
     # @param parameter_name
@@ -167,7 +169,7 @@ module PuppetStrings::Markdown
     # @return [Array] enum tag hashes that have a parent parameter_name
     def enums_for_param(parameter_name)
       enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
-      enums_for_p unless enums_for_p.nil? || enums_for_p.length.zero?
+      enums_for_p unless enums_for_p.nil? || enums_for_p.empty?
     end
 
     # @return [Hash] any defaults found for the component
@@ -198,7 +200,7 @@ module PuppetStrings::Markdown
       return unless text
 
       text.split("\n").map! { |line|
-        line.length > line_width ? line.gsub(%r{(.{1,#{line_width}})(\s+|$)}, "\\1#{break_sequence}").strip : line
+        line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
       } * break_sequence
     end
 

data/lib/puppet-strings/markdown/data_type.rb

@@ -5,17 +5,16 @@ require 'puppet-strings/markdown/base'
 module PuppetStrings::Markdown
   # This class encapsualtes ruby data types and puppet type aliases
   class DataType < Base
-    attr_reader :alias_of
-    attr_reader :functions
+    attr_reader :alias_of, :functions
 
     group_name 'Data types'
-    yard_types [:puppet_data_type, :puppet_data_type_alias]
+    yard_types %i[puppet_data_type puppet_data_type_alias]
 
     def initialize(registry)
       @template = 'data_type.erb'
       super(registry, 'data type')
       @alias_of = registry[:alias_of] unless registry[:alias_of].nil?
-      @functions = @registry[:functions].nil? ? nil : @registry[:functions].map { |func| DataType::Function.new(func) }
+      @functions = @registry[:functions]&.map { |func| DataType::Function.new(func) }
     end
 
     def render

data/lib/puppet-strings/markdown/function.rb

@@ -25,11 +25,11 @@ module PuppetStrings::Markdown
 
     def type
       t = @registry[:type]
-      if %r{ruby4x}.match?(t)
+      if t.include?('ruby4x')
         'Ruby 4.x API'
-      elsif %r{ruby3}.match?(t)
+      elsif t.include?('ruby3')
         'Ruby 3.x API'
-      elsif %r{ruby}.match?(t)
+      elsif t.include?('ruby')
         'Ruby'
       else
         'Puppet Language'
@@ -37,11 +37,11 @@ module PuppetStrings::Markdown
     end
 
     def error_type(type)
-      "`#{type.split(' ')[0]}`"
+      "`#{type.split[0]}`"
     end
 
     def error_text(text)
-      text.split(' ').drop(1).join(' ').to_s
+      text.split.drop(1).join(' ').to_s
     end
   end
 

data/lib/puppet-strings/markdown/resource_type.rb

@@ -50,7 +50,7 @@ module PuppetStrings::Markdown
 
     def regex_in_data_type?(data_type)
       m = data_type.match(%r{\w+\[/.*/\]})
-      m unless m.nil? || m.length.zero?
+      m unless m.nil? || m.to_a.empty?
     end
   end
 end

data/lib/puppet-strings/markdown/templates/classes_and_defines.erb

@@ -8,6 +8,10 @@
 <%= "The #{name} class." %>
 <% end -%>
 
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
+<% end -%>
 <% if todo -%>
 * **TODO** <%= todo %>
 

data/lib/puppet-strings/markdown/templates/data_type.erb

@@ -8,6 +8,10 @@
 <%= "The #{name} data type." %>
 <% end -%>
 
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
+<% end -%>
 <% if todo -%>
 * **TODO** <%= todo %>
 

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

@@ -11,6 +11,10 @@ Type: <%= type %>
 <% else -%>
 <%= "The #{name} function." %>
 
+<% end -%>
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
 <% end -%>
 <% if todo -%>
 * **TODO** <%= todo %>

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

@@ -8,6 +8,10 @@
 <%= "The #{name} type." %>
 <% end -%>
 
+<% if deprecated -%>
+* **DEPRECATED** <%= deprecated %>
+
+<% end -%>
 <% if todo -%>
 * **TODO** <%= todo %>
 

data/lib/puppet-strings/markdown.rb

@@ -23,7 +23,7 @@ module PuppetStrings::Markdown
       PuppetStrings::Markdown::Function,
       PuppetStrings::Markdown::DataType,
       PuppetStrings::Markdown::PuppetTask,
-      PuppetStrings::Markdown::PuppetPlan,
+      PuppetStrings::Markdown::PuppetPlan
     ]
   end
 
@@ -33,14 +33,14 @@ module PuppetStrings::Markdown
     output = [
       "# Reference\n\n",
       "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n",
-      "## Table of Contents\n\n",
+      "## Table of Contents\n\n"
     ]
 
     # Create table of contents
     template = erb(File.join(__dir__, 'markdown', 'templates', 'table_of_contents.erb'))
     groups.each do |group|
       group_name = group.group_name
-      items = group.items.map { |item| item.toc_info }
+      items = group.items.map(&:toc_info)
       has_private = items.any? { |item| item[:private] }
       has_public = items.any? { |item| !item[:private] }
 
@@ -49,14 +49,14 @@ module PuppetStrings::Markdown
 
     # Create actual contents
     groups.each do |group|
-      items = group.items.reject { |item| item.private? }
+      items = group.items.reject(&:private?)
       unless items.empty?
         output << "## #{group.group_name}\n\n"
-        output.append(items.map { |item| item.render })
+        output.append(items.map(&:render))
       end
     end
 
-    output.join('')
+    output.join
   end
 
   # mimicks the behavior of the json render, although path will never be nil
@@ -66,7 +66,7 @@ module PuppetStrings::Markdown
       puts generate
       exit
     else
-      File.open(path, 'w') { |file| file.write(generate) }
+      File.write(path, generate)
       YARD::Logger.instance.debug "Wrote markdown to #{path}"
     end
   end
@@ -76,11 +76,9 @@ module PuppetStrings::Markdown
   # @param [String] path The full path to the template file.
   # @return [ERB] Template
   def self.erb(path)
-    if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0')
-      ERB.new(File.read(path), trim_mode: '-')
-    else
+    unless Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('2.6.0')
       # This outputs warnings in Ruby 2.6+.
-      ERB.new(File.read(path), nil, '-')
     end
+    ERB.new(File.read(path), trim_mode: '-')
   end
 end

data/lib/puppet-strings/tasks/generate.rb

@@ -13,7 +13,7 @@ namespace :strings do
     options = {
       debug: args[:debug] == 'true',
       backtrace: args[:backtrace] == 'true',
-      markup: args[:markup] || 'markdown',
+      markup: args[:markup] || 'markdown'
     }
 
     raise('Error: Both JSON and Markdown output have been selected. Please select one.') if args[:json] == 'true' && args[:markdown] == 'true'
@@ -29,13 +29,15 @@ namespace :strings do
     # @return nil
     def parse_format_option(args, options, format)
       return unless args.has_key? format
-      options[format] = args[format] == 'false' || args[format].empty? ? false : true
+
+      options[format] = !(args[format] == 'false' || args[format].empty?)
       return unless options[format]
+
       options[:path] = args[format] == 'true' ? nil : args[format]
     end
     # rubocop:enable Style/PreferredHashMethods
 
-    [:json, :markdown].each { |format| parse_format_option(args, options, format) }
+    %i[json markdown].each { |format| parse_format_option(args, options, format) }
 
     warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args]
     options[:yard_args] = args[:yard_args].split if args.key? :yard_args

data/lib/puppet-strings/tasks/gh_pages.rb

@@ -30,7 +30,7 @@ namespace :strings do
     task :configure do
       unless File.exist?(File.join('doc', '_config.yml'))
         Dir.chdir('doc') do
-          File.open('_config.yml', 'w+') { |f| f.write('include: _index.html') }
+          File.write('_config.yml', 'include: _index.html')
         end
       end
     end
@@ -48,11 +48,11 @@ namespace :strings do
     end
 
     desc 'Update docs on the gh-pages branch and push to GitHub.'
-    task update: [
-      :checkout,
-      :'strings:generate',
-      :configure,
-      :push,
+    task update: %i[
+      checkout
+      strings:generate
+      configure
+      push
     ]
   end
 end

data/lib/puppet-strings/tasks/validate.rb

@@ -10,7 +10,7 @@ namespace :strings do
       filename = 'REFERENCE.md'
 
       unless File.exist?(filename)
-        STDERR.puts "#{filename} does not exist"
+        warn "#{filename} does not exist"
         exit 1
       end
 
@@ -24,7 +24,7 @@ namespace :strings do
           backtrace: args[:backtrace] == 'true',
           json: false,
           markdown: true,
-          path: file,
+          path: file
         }
         PuppetStrings.generate(patterns, options)
 
@@ -34,7 +34,7 @@ namespace :strings do
       existing = File.read(filename)
 
       if generated != existing
-        STDERR.puts "#{filename} is outdated"
+        warn "#{filename} is outdated"
         exit 1
       end
     end

data/lib/puppet-strings/tasks.rb

@@ -3,9 +3,12 @@
 require 'rake'
 require 'rake/tasklib'
 
+# Ensure PuppetStrings is loaded.
+module PuppetStrings end
+
 # The module for Puppet Strings rake tasks.
 module PuppetStrings::Tasks
-  require 'puppet-strings/tasks/generate.rb'
-  require 'puppet-strings/tasks/gh_pages.rb'
-  require 'puppet-strings/tasks/validate.rb'
+  require 'puppet-strings/tasks/generate'
+  require 'puppet-strings/tasks/gh_pages'
+  require 'puppet-strings/tasks/validate'
 end

data/lib/puppet-strings/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PuppetStrings
-  VERSION = '3.0.0'
+  VERSION = '4.0.0.rc.1'
 end

data/lib/puppet-strings/yard/code_objects/base.rb

@@ -7,9 +7,9 @@ class PuppetStrings::Yard::CodeObjects::Base < YARD::CodeObjects::NamespaceObjec
   # @return Returns the code object.
   def self.new(*args)
     # Skip the super class' implementation because it detects :: in names and this will cause namespaces in the output we don't want
-    object = Object.class.instance_method(:new).bind(self).call(*args)
+    object = Object.class.instance_method(:new).bind_call(self, *args)
     existing = YARD::Registry.at(object.path)
-    object = existing if existing && existing.class == self
+    object = existing if existing.instance_of?(self)
     yield(object) if block_given?
     object
   end

data/lib/puppet-strings/yard/code_objects/class.rb

@@ -20,8 +20,7 @@ end
 
 # Implements the Puppet class code object.
 class PuppetStrings::Yard::CodeObjects::Class < PuppetStrings::Yard::CodeObjects::Base
-  attr_reader :statement
-  attr_reader :parameters
+  attr_reader :statement, :parameters
 
   # Initializes a Puppet class code object.
   # @param [PuppetStrings::Parsers::ClassStatement] statement The class statement that was parsed.

data/lib/puppet-strings/yard/code_objects/data_type.rb

@@ -87,14 +87,14 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
     hash[:name] = name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring, [:param, :option, :enum, :return, :example])
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example])
     hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
     hash[:source] = source unless source.nil? || source.empty?
     hash[:functions] = functions.map do |func|
       {
         name: func.name,
         signature: func.signature,
-        docstring: PuppetStrings::Yard::Util.docstring_to_hash(func.docstring, [:param, :option, :enum, :return, :example])
+        docstring: PuppetStrings::Yard::Util.docstring_to_hash(func.docstring, %i[param option enum return example])
       }
     end
     hash

data/lib/puppet-strings/yard/code_objects/defined_type.rb

@@ -20,8 +20,7 @@ end
 
 # Implements the Puppet defined type code object.
 class PuppetStrings::Yard::CodeObjects::DefinedType < PuppetStrings::Yard::CodeObjects::Base
-  attr_reader :statement
-  attr_reader :parameters
+  attr_reader :statement, :parameters
 
   # Initializes a Puppet defined type code object.
   # @param [PuppetStrings::Parsers::DefinedTypeStatement] statement The defined type statement that was parsed.

data/lib/puppet-strings/yard/code_objects/function.rb

@@ -65,16 +65,16 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
     return '' if has_tag? :overload
 
     tags = self.tags(:param)
-    args = @parameters.map { |parameter|
+    args = @parameters.map do |parameter|
       name, default = parameter
       tag = tags.find { |t| t.name == name } if tags
       type = tag&.types ? "#{tag.type} " : 'Any '
       prefix = (name[0]).to_s if name.start_with?('*', '&')
-      name = name[1..-1] if prefix
+      name = name[1..] if prefix
       default = " = #{default}" if default
       "#{type}#{prefix}$#{name}#{default}"
-    }.join(', ')
-    @name.to_s + '(' + args + ')'
+    end.join(', ')
+    "#{@name}(#{args})"
   end
 
   # Converts the code object to a hash representation.
@@ -91,10 +91,10 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
     if has_tag? :overload
       # loop over overloads and append onto the signatures array
       tags(:overload).each do |o|
-        hash[:signatures] << { signature: o.signature, docstring: PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, [:param, :option, :enum, :return, :example]) }
+        hash[:signatures] << { signature: o.signature, docstring: PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, %i[param option enum return example]) }
       end
     else
-      hash[:signatures] << { signature: signature, docstring: PuppetStrings::Yard::Util.docstring_to_hash(docstring, [:param, :option, :enum, :return, :example]) }
+      hash[:signatures] << { signature: signature, docstring: PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example]) }
     end
 
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)

data/lib/puppet-strings/yard/code_objects/plan.rb

@@ -20,8 +20,7 @@ end
 
 # Implements the Puppet plan code object.
 class PuppetStrings::Yard::CodeObjects::Plan < PuppetStrings::Yard::CodeObjects::Base
-  attr_reader :statement
-  attr_reader :parameters
+  attr_reader :statement, :parameters
 
   # Initializes a Puppet plan code object.
   # @param [PuppetStrings::Parsers::PlanStatement] statement The plan statement that was parsed.

data/lib/puppet-strings/yard/code_objects/type.rb

@@ -158,7 +158,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
     provider_param = Parameter.new(
       'provider',
       "The specific backend to use for this `#{name}` resource. You will seldom need " \
-      'to specify this --- Puppet will usually discover the appropriate provider for your platform.',
+      'to specify this --- Puppet will usually discover the appropriate provider for your platform.'
     )
 
     @parameters ||= []
@@ -185,11 +185,11 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
     hash[:line] = line
 
     hash[:docstring]  = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    hash[:properties] = properties.sort_by { |p| p.name }.map(&:to_hash) if properties && !properties.empty?
-    hash[:parameters] = parameters.sort_by { |p| p.name }.map(&:to_hash) if parameters && !parameters.empty?
-    hash[:checks]     = checks.sort_by { |c| c.name }.map(&:to_hash) if checks && !checks.empty?
-    hash[:features]   = features.sort_by { |f| f.name }.map(&:to_hash) if features && !features.empty?
-    hash[:providers]  = providers.sort_by { |p| p.name }.map(&:to_hash) if providers && !providers.empty?
+    hash[:properties] = properties.sort_by(&:name).map(&:to_hash) if properties && !properties.empty?
+    hash[:parameters] = parameters.sort_by(&:name).map(&:to_hash) if parameters && !parameters.empty?
+    hash[:checks]     = checks.sort_by(&:name).map(&:to_hash) if checks && !checks.empty?
+    hash[:features]   = features.sort_by(&:name).map(&:to_hash) if features && !features.empty?
+    hash[:providers]  = providers.sort_by(&:name).map(&:to_hash) if providers && !providers.empty?
 
     hash
   end

data/lib/puppet-strings/yard/handlers/helpers.rb

@@ -4,6 +4,7 @@
 module PuppetStrings::Yard::Handlers::Helpers
   def self.validate_summary_tag(object)
     return unless object.has_tag?(:summary) && object.tag(:summary).text.length > 140
+
     log.warn "The length of the summary for #{object.type} '#{object.name}' exceeds the recommended limit of 140 characters."
   end
 end

data/lib/puppet-strings/yard/handlers/json/task_handler.rb

@@ -26,6 +26,7 @@ class PuppetStrings::Yard::Handlers::JSON::TaskHandler < PuppetStrings::Yard::Ha
 
   def validate_params
     return if @statement.parameters.empty?
+
     @statement.parameters.each do |param, val|
       log.warn "Missing description for param '#{param}' in #{@kind}" if val['description'].nil?
     end

data/lib/puppet-strings/yard/handlers/puppet/base.rb

@@ -37,9 +37,9 @@ class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
 
       # Warn if the parameter type and tag types don't match
       if parameter.type && tag.types && !tag.types.empty? && parameter.type != tag.types[0]
-        log.warn "The type of the @param tag for parameter '#{parameter.name}' "\
-          "does not match the parameter type specification near #{statement.file}:#{statement.line}: "\
-          'ignoring in favor of parameter type information.'
+        log.warn "The type of the @param tag for parameter '#{parameter.name}' " \
+                 "does not match the parameter type specification near #{statement.file}:#{statement.line}: " \
+                 'ignoring in favor of parameter type information.'
       end
 
       if parameter.type

data/lib/puppet-strings/yard/handlers/ruby/base.rb

@@ -6,7 +6,7 @@ require 'ripper'
 class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
   # A regular expression for detecting the start of a Ruby heredoc.
   # Note: the first character of the heredoc start may have been cut off by YARD.
-  HEREDOC_START = %r{^<?<[\-~]?['"]?(\w+)['"]?[^\n]*[\n]?}.freeze
+  HEREDOC_START = /^<?<[-~]?['"]?(\w+)['"]?[^\n]*\n?/.freeze
 
   protected
 
@@ -18,7 +18,7 @@ class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
 
     case node.type
     when :symbol, :symbol_literal
-      node.source[1..-1]
+      node.source[1..]
     when :label
       node.source[0..-2]
     when :dyna_symbol

data/lib/puppet-strings/yard/handlers/ruby/data_type_handler.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# rubocop:disable Naming/MethodName
-
 require 'puppet-strings/yard/handlers/helpers'
 require 'puppet-strings/yard/handlers/ruby/base'
 require 'puppet-strings/yard/code_objects'
@@ -255,7 +253,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
       begin
         callable_type = Puppet::Pops::Types::TypeParser.singleton.parse(func_type)
         if callable_type.is_a?(Puppet::Pops::Types::PCallableType)
-          func_hash[:param_types] = callable_type.param_types.map { |pt| pt.to_s }
+          func_hash[:param_types] = callable_type.param_types.map(&:to_s)
           func_hash[:return_type] = callable_type.return_type.to_s
         else
           log.warn "The function definition for '#{key}' near #{object.file}:#{object.line} is not a Callable type"
@@ -360,9 +358,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
     # Puppet Data Type function invocation. So instead we derive a signature from the method definition.
     object.meths.each do |meth|
       params = ''
-      unless meth.docstring.tags(:param).empty?
-        params += '(' + meth.docstring.tags(:param).map { |t| t.name }.join(', ') + ')'
-      end
+      params += "(#{meth.docstring.tags(:param).map(&:name).join(', ')})" unless meth.docstring.tags(:param).empty?
       meth.signature = "#{object.name}.#{meth.name}" + params
     end
 
@@ -379,9 +375,9 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
         if tag.tag_name == 'param'
           index += 1
           if index > actual_function[:param_types].count
-            log.warn "The @param tag for '#{tag.name}' should not exist for function "\
-            "'#{meth.name}' that is defined near #{object.file}:#{object.line}. "\
-            "Expected only #{actual_function[:param_types].count} parameter/s"
+            log.warn "The @param tag for '#{tag.name}' should not exist for function " \
+                     "'#{meth.name}' that is defined near #{object.file}:#{object.line}. " \
+                     "Expected only #{actual_function[:param_types].count} parameter/s"
             true
           else
             false