puppet-strings 2.9.0 → 3.0.0

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

@@ -13,7 +13,7 @@ class PuppetStrings::Yard::CodeObjects::DefinedTypes < PuppetStrings::Yard::Code
   # Gets the display name of the group.
   # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
   # @return [String] Returns the display name of the group.
-  def name(prefix = false)
+  def name(_prefix = false)
     'Defined Types'
   end
 end
@@ -52,7 +52,7 @@ class PuppetStrings::Yard::CodeObjects::DefinedType < PuppetStrings::Yard::CodeO
     hash[:file] = file
     hash[:line] = line
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
+    defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
     hash[:source] = source unless source.nil? || source.empty?
     hash

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

@@ -8,13 +8,13 @@ class PuppetStrings::Yard::CodeObjects::Functions < PuppetStrings::Yard::CodeObj
   # @param [Symbol] type The function type to get the group for.
   # @return Returns the singleton instance of the group.
   def self.instance(type)
-    super("puppet_functions_#{type}".intern)
+    super("puppet_functions_#{type}".to_sym)
   end
 
   # Gets the display name of the group.
   # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
   # @return [String] Returns the display name of the group.
-  def name(prefix = false)
+  def name(_prefix = false)
     'Puppet Functions'
   end
 end
@@ -62,18 +62,18 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
   # Gets the Puppet signature of the function (single overload only).
   # @return [String] Returns the Puppet signature of the function.
   def signature
-    return '' if self.has_tag? :overload
+    return '' if has_tag? :overload
 
     tags = self.tags(:param)
-    args = @parameters.map do |parameter|
+    args = @parameters.map { |parameter|
       name, default = parameter
       tag = tags.find { |t| t.name == name } if tags
       type = tag&.types ? "#{tag.type} " : 'Any '
-      prefix = "#{name[0]}" if name.start_with?('*', '&')
+      prefix = (name[0]).to_s if name.start_with?('*', '&')
       name = name[1..-1] if prefix
       default = " = #{default}" if default
       "#{type}#{prefix}$#{name}#{default}"
-    end.join(', ')
+    }.join(', ')
     @name.to_s + '(' + args + ')'
   end
 
@@ -88,17 +88,17 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
     hash[:type] = @function_type.to_s
     hash[:signatures] = []
 
-    if self.has_tag? :overload
+    if has_tag? :overload
       # loop over overloads and append onto the signatures array
-      self.tags(:overload).each do |o|
-        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, %i[param option enum return example]) }
+      tags(:overload).each do |o|
+        hash[:signatures] << { signature: o.signature, docstring: PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, [:param, :option, :enum, :return, :example]) }
       end
     else
-      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example]) }
+      hash[:signatures] << { signature: signature, docstring: PuppetStrings::Yard::Util.docstring_to_hash(docstring, [:param, :option, :enum, :return, :example]) }
     end
 
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
+    defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
     hash[:source] = source unless source.nil? || source.empty?
     hash

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

@@ -13,7 +13,7 @@ class PuppetStrings::Yard::CodeObjects::Group < PuppetStrings::Yard::CodeObjects
     instance = P(:root, key)
     return instance unless instance.is_a?(YARD::CodeObjects::Proxy)
 
-    instance = self.new(:root, key)
+    instance = new(:root, key)
     instance.visibility = :hidden
     P(:root).children << instance
     instance

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

@@ -2,6 +2,7 @@
 
 require 'puppet-strings/yard/code_objects/group'
 
+# Implements the group for Puppet plans.
 class PuppetStrings::Yard::CodeObjects::Plans < PuppetStrings::Yard::CodeObjects::Group
   # Gets the singleton instance of the group.
   # @return Returns the singleton instance of the group.
@@ -12,11 +13,12 @@ class PuppetStrings::Yard::CodeObjects::Plans < PuppetStrings::Yard::CodeObjects
   # Gets the display name of the group.
   # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
   # @return [String] Returns the display name of the group.
-  def name(prefix = false)
+  def name(_prefix = false)
     'Puppet Plans'
   end
 end
 
+# Implements the Puppet plan code object.
 class PuppetStrings::Yard::CodeObjects::Plan < PuppetStrings::Yard::CodeObjects::Base
   attr_reader :statement
   attr_reader :parameters
@@ -50,7 +52,7 @@ class PuppetStrings::Yard::CodeObjects::Plan < PuppetStrings::Yard::CodeObjects:
     hash[:file] = file
     hash[:line] = line
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
-    defaults = Hash[*parameters.reject{ |p| p[1].nil? }.flatten]
+    defaults = Hash[*parameters.reject { |p| p[1].nil? }.flatten]
     hash[:defaults] = defaults unless defaults.nil? || defaults.empty?
     hash[:source] = source unless source.nil? || source.empty?
     hash

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

@@ -8,13 +8,13 @@ class PuppetStrings::Yard::CodeObjects::Providers < PuppetStrings::Yard::CodeObj
   # @param [String] type The resource type name for the provider.
   # @return Returns the singleton instance of the group.
   def self.instance(type)
-    super("puppet_providers_#{type}".intern)
+    super("puppet_providers_#{type}".to_sym)
   end
 
   # Gets the display name of the group.
   # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
   # @return [String] Returns the display name of the group.
-  def name(prefix = false)
+  def name(_prefix = false)
     'Providers'
   end
 end

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

@@ -11,9 +11,9 @@ class PuppetStrings::Yard::CodeObjects::Tasks < PuppetStrings::Yard::CodeObjects
   end
 
   # Gets the display name of the group.
-  # @param [Boolean] prefix whether to show a prefix.
+  # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
   # @return [String] Returns the display name of the group.
-  def name(prefix = false)
+  def name(_prefix = false)
     'Puppet Tasks'
   end
 end
@@ -45,11 +45,11 @@ class PuppetStrings::Yard::CodeObjects::Task < PuppetStrings::Yard::CodeObjects:
 
   def parameters
     parameters = []
-    statement.parameters.each do |name,props|
+    statement.parameters.each do |name, props|
       parameters.push({ name: name.to_s,
                         tag_name: 'param',
-                        text: props['description'] || "",
-                        types: [props['type']] || "" })
+                        text: props['description'] || '',
+                        types: [props['type']] || '' })
     end
     parameters
   end
@@ -66,7 +66,6 @@ class PuppetStrings::Yard::CodeObjects::Task < PuppetStrings::Yard::CodeObjects:
       },
       source: statement.source,
       supports_noop: statement.json['supports_noop'] || false,
-      input_method: statement.json['input_method']
-    }
+      input_method: statement.json['input_method'] }
   end
 end

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

@@ -14,7 +14,7 @@ class PuppetStrings::Yard::CodeObjects::Types < PuppetStrings::Yard::CodeObjects
   # Gets the display name of the group.
   # @param [Boolean] prefix whether to show a prefix. Ignored for Puppet group namespaces.
   # @return [String] Returns the display name of the group.
-  def name(prefix = false)
+  def name(_prefix = false)
     'Resource Types'
   end
 end
@@ -87,7 +87,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
     # @param [String] docstring The docstring of the feature.
     def initialize(name, docstring)
       @name = name
-      @docstring = PuppetStrings::Yard::Util.scrub_string(docstring).gsub("\n", ' ')
+      @docstring = PuppetStrings::Yard::Util.scrub_string(docstring).tr("\n", ' ')
     end
 
     # Converts the feature to a hash representation.
@@ -148,7 +148,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
   end
 
   def parameters
-    @parameters ||= []  # guard against not filled parameters
+    @parameters ||= [] # guard against not filled parameters
     # just return params if there are no providers
     return @parameters if providers.empty?
 
@@ -157,8 +157,8 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
 
     provider_param = Parameter.new(
       'provider',
-      "The specific backend to use for this `#{self.name.to_s}` resource. You will seldom need " + \
-      "to specify this --- Puppet will usually discover the appropriate provider for your platform."
+      "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.',
     )
 
     @parameters ||= []
@@ -169,7 +169,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects:
   # render-time. For now, this should re-resolve on every call.
   # may be able to memoize this
   def providers
-    providers = YARD::Registry.all("puppet_providers_#{name}".intern)
+    providers = YARD::Registry.all("puppet_providers_#{name}".to_sym)
     return providers if providers.empty?
 
     providers.first.children

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

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
+# Implements a helper that logs a warning if a summary tag has more than 140 characters
 module PuppetStrings::Yard::Handlers::Helpers
-  # Logs a warning if a summary tag has more than 140 characters
   def self.validate_summary_tag(object)
-    if 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
+    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/base.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
+# Implements the base class for all JSON handlers.
 class PuppetStrings::Yard::Handlers::JSON::Base < YARD::Handlers::Base
   def self.handles?(statement)
-    handlers.any? {|handler| statement.is_a?(handler)}
+    handlers.any? { |handler| statement.is_a?(handler) }
   end
 end

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

@@ -4,6 +4,7 @@ require 'puppet-strings/yard/handlers/json/base'
 require 'puppet-strings/yard/parsers'
 require 'puppet-strings/yard/parsers/json/parser'
 
+# Implements the handler for JSON task metadata.
 class PuppetStrings::Yard::Handlers::JSON::TaskHandler < PuppetStrings::Yard::Handlers::JSON::Base
   handles PuppetStrings::Yard::Parsers::JSON::TaskStatement
   namespace_only
@@ -24,10 +25,9 @@ class PuppetStrings::Yard::Handlers::JSON::TaskHandler < PuppetStrings::Yard::Ha
   end
 
   def validate_params
-    unless @statement.parameters.empty?
-      @statement.parameters.each do |param, val|
-        log.warn "Missing description for param '#{param}' in #{@kind}" if val['description'].nil?
-      end
+    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
   end
 end

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

@@ -6,10 +6,11 @@ class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
   # @param statement The statement that was parsed.
   # @return [Boolean] Returns true if the statement is handled by this handler or false if not.
   def self.handles?(statement)
-    handlers.any? {|handler| statement.is_a?(handler)}
+    handlers.any? { |handler| statement.is_a?(handler) }
   end
 
   protected
+
   # Sets the parameter tag types for the given code object.
   # This also performs some validation on the parameter tags.
   # @param object The code object to set the parameter tag types for.
@@ -35,7 +36,11 @@ class PuppetStrings::Yard::Handlers::Puppet::Base < YARD::Handlers::Base
       end
 
       # Warn if the parameter type and tag types don't match
-      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." if parameter.type && tag.types && !tag.types.empty? && parameter.type != tag.types[0]
+      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.'
+      end
 
       if parameter.type
         tag.types = [parameter.type]

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

@@ -36,7 +36,8 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
   end
 
   private
-  def add_return_tag(object, type=nil)
+
+  def add_return_tag(object, type = nil)
     tag = object.tag(:return)
     if tag
       if (type && tag.types && tag.types.first) && (type != tag.types.first)
@@ -47,7 +48,7 @@ class PuppetStrings::Yard::Handlers::Puppet::FunctionHandler < PuppetStrings::Ya
       return
     end
     log.warn "Missing @return tag near #{statement.file}:#{statement.line}."
-    type = type || 'Any'
+    type ||= 'Any'
     object.add_tag YARD::Tags::Tag.new(:return, '', type)
   end
 end

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

@@ -6,9 +6,10 @@ 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 = /^<?<[\-~]?['"]?(\w+)['"]?[^\n]*[\n]?/
+  HEREDOC_START = %r{^<?<[\-~]?['"]?(\w+)['"]?[^\n]*[\n]?}.freeze
 
   protected
+
   # Converts the given Ruby AST node to a string representation.
   # @param node The Ruby AST node to convert.
   # @return [String] Returns a string representation of the node or nil if a string representation was not possible.
@@ -33,7 +34,7 @@ class PuppetStrings::Yard::Handlers::Ruby::Base < YARD::Handlers::Ruby::Base
       source = node.source
       if source =~ HEREDOC_START
         lines = source.split("\n")
-        source = lines[1..(lines.last.include?($1[0..-2]) ? -2 : -1)].join("\n") if lines.size > 1
+        source = lines[1..(lines.last.include?(Regexp.last_match(1)[0..-2]) ? -2 : -1)].join("\n") if lines.size > 1
       end
 
       source

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

@@ -1,5 +1,7 @@
 # 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'
@@ -65,7 +67,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
     parsed_interface = nil
 
     # Recursively traverse the block looking for the first valid 'interface' call
-    interface_node = find_ruby_ast_node(block, true) do |node|
+    find_ruby_ast_node(block, true) do |node|
       next false unless node.is_a?(YARD::Parser::Ruby::MethodCallNode) &&
                         node.method_name &&
                         node.method_name.source == 'interface'
@@ -102,7 +104,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
   # @yieldreturn [Boolean] Whether the node was what was searched for
   # @return [YARD::Parser::Ruby::AstNode, nil]
   def find_ruby_ast_node(ast_node, recurse = false, &block)
-    raise ArgumentError, 'find_ruby_ast_node requires a block' unless block_given?
+    raise ArgumentError, 'find_ruby_ast_node requires a block' unless block
 
     is_found = yield ast_node
     return ast_node if is_found
@@ -136,7 +138,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
   # Anything else is ignored
   class LazyLiteralEvaluator
     def initialize
-      @literal_visitor = ::Puppet::Pops::Visitor.new(self, "literal", 0, 0)
+      @literal_visitor = ::Puppet::Pops::Visitor.new(self, 'literal', 0, 0)
     end
 
     def literal(ast)
@@ -150,12 +152,12 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
 
     def literal_AccessExpression(o)
       # Extract the raw text of the Access Expression
-      ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(o).extract_text
+      PuppetStrings::Yard::Util.ast_to_text(o)
     end
 
     def literal_QualifiedReference(o)
       # Extract the raw text of the Qualified Reference
-      ::Puppet::Pops::Adapters::SourcePosAdapter.adapt(o).extract_text
+      PuppetStrings::Yard::Util.ast_to_text(o)
     end
 
     # ----- The following methods are the same as the original Literal_evaluator
@@ -187,11 +189,11 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
       o.value
     end
 
-    def literal_LiteralUndef(o)
+    def literal_LiteralUndef(_o)
       nil
     end
 
-    def literal_LiteralDefault(o)
+    def literal_LiteralDefault(_o)
       :default
     end
 
@@ -210,9 +212,8 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
     end
 
     def literal_LiteralHash(o)
-      o.entries.reduce({}) do |result, entry|
+      o.entries.each_with_object({}) do |entry, result|
         result[literal(entry.key)] = literal(entry.value)
-        result
       end
     end
   end
@@ -235,7 +236,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
         default   = value['value'] unless value['value'].nil?
       end
       data_type = [data_type] unless data_type.nil? || data_type.is_a?(Array)
-      params_hash[key] = { :types => data_type, :default => default }
+      params_hash[key] = { types: data_type, default: default }
     end
 
     params_hash
@@ -250,7 +251,7 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
     return funcs_hash if hash.nil? || hash['functions'].nil? || hash['functions'].empty?
 
     hash['functions'].each do |key, func_type|
-      func_hash = { :param_types => [], :return_type => nil }
+      func_hash = { param_types: [], return_type: nil }
       begin
         callable_type = Puppet::Pops::Types::TypeParser.singleton.parse(func_type)
         if callable_type.is_a?(Puppet::Pops::Types::PCallableType)
@@ -378,7 +379,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
@@ -392,14 +395,14 @@ class PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler < PuppetStrings::Yard
     # Add missing params
     if meth.docstring.tags(:param).count < actual_function[:param_types].count
       start = meth.docstring.tags(:param).count + 1
-      (start..actual_function[:param_types].count).each do |index| # Using 1-based index here instead of usual zero
-        meth.add_tag(YARD::Tags::Tag.new(:param, '', actual_function[:param_types][index - 1], "param#{index}"))
+      (start..actual_function[:param_types].count).each do |param_type_index| # Using 1-based index here instead of usual zero
+        meth.add_tag(YARD::Tags::Tag.new(:param, '', actual_function[:param_types][param_type_index - 1], "param#{param_type_index}"))
       end
     end
 
     # Ensure the parameter types are correct
-    meth.docstring.tags(:param).each_with_index do |tag, index|
-      actual_types = [actual_function[:param_types][index]]
+    meth.docstring.tags(:param).each_with_index do |tag, actual_type_index|
+      actual_types = [actual_function[:param_types][actual_type_index]]
       if tag.types != actual_types
         log.warn "The @param tag for '#{tag.name}' for function '#{meth.name}' has a different type definition than the actual function near #{object.file}:#{object.line}. Expected #{actual_types}"
         tag.types = actual_types