puppet 8.3.1 → 8.4.0

data/lib/puppet/parameter/value_collection.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative '../../puppet/parameter/value'
 
 # A collection of values and regular expressions, used for specifying allowed values
@@ -12,7 +13,6 @@ require_relative '../../puppet/parameter/value'
 # @api private
 #
 class Puppet::Parameter::ValueCollection
-
   # Aliases the given existing _other_ value with the additional given _name_.
   # @return [void]
   # @api private
@@ -121,7 +121,7 @@ class Puppet::Parameter::ValueCollection
   # @option options [Symbol] :event The event that should be emitted when this value is set.
   # @todo Option :event original comment says "event should be returned...", is "returned" the correct word
   #   to use?
- # @option options [Symbol] :invalidate_refreshes True if a change on this property should invalidate and
+  # @option options [Symbol] :invalidate_refreshes True if a change on this property should invalidate and
   #   remove any scheduled refreshes (from notify or subscribe) targeted at the same resource. For example, if
   #   a change in this property takes into account any changes that a scheduled refresh would have performed,
   #   then the scheduled refresh would be deleted.
@@ -134,11 +134,11 @@ class Puppet::Parameter::ValueCollection
     call_opt = options[:call]
     unless call_opt.nil?
       devfail "Cannot use obsolete :call value '#{call_opt}' for property '#{self.class.name}'" unless call_opt == :none || call_opt == :instead
-      #TRANSLATORS ':call' is a property and should not be translated
+      # TRANSLATORS ':call' is a property and should not be translated
       message = _("Property option :call is deprecated and no longer used.")
       message += ' ' + _("Please remove it.")
       Puppet.deprecation_warning(message)
-      options = options.reject { |k,v| k == :call }
+      options = options.reject { |k,_v| k == :call }
     end
 
     value = Puppet::Parameter::Value.new(name)
@@ -184,7 +184,7 @@ class Puppet::Parameter::ValueCollection
   def validate(value)
     return if empty?
 
-    unless @values.detect {|name, v| v.match?(value)}
+    unless @values.detect {|_name, v| v.match?(value)}
       str = _("Invalid value %{value}.") % { value: value.inspect }
       str += " " + _("Valid values are %{value_list}.") % { value_list: values.join(", ") } unless values.empty?
       str += " " + _("Valid values match %{pattern}.") % { pattern: regexes.join(", ") } unless regexes.empty?

data/lib/puppet/parameter.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative '../puppet/util/logging'
 require_relative '../puppet/util/docs'
 
@@ -86,12 +87,13 @@ class Puppet::Parameter
       else
         if value.nil?
           raise Puppet::DevError,
-            "Either a default value or block must be provided"
+                "Either a default value or block must be provided"
         end
         define_method(:default) do value end
       end
     end
 
+    # rubocop:disable Naming/PredicateName
     def sensitive(value = nil, &block)
       if block
         define_method(:is_sensitive, &block)
@@ -99,6 +101,7 @@ class Puppet::Parameter
         define_method(:is_sensitive) do value end
       end
     end
+    # rubocop:enable Naming/PredicateName
 
     # Produces a documentation string.
     # If an enumeration of _valid values_ has been defined, it is appended to the documentation
@@ -330,7 +333,6 @@ class Puppet::Parameter
     resource.version
   end
 
-
   # Initializes the parameter with a required resource reference and optional attribute settings.
   # The option `:resource` must be specified or an exception is raised. Any additional options passed
   # are used to initialize the attributes of this parameter by treating each key in the `options` hash as
@@ -384,7 +386,6 @@ class Puppet::Parameter
   def noop
     @noop ||= false
     tmp = @noop || self.resource.noop || Puppet[:noop] || false
-    #debug "noop is #{tmp}"
     tmp
   end
 

data/lib/puppet/parser/abstract_compiler.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 module Puppet::Parser::AbstractCompiler
-
   # Returns the catalog for a compilation. Must return a Puppet::Resource::Catalog or fail with an 
   # error if the specific compiler does not support catalog operations.
   #
@@ -33,5 +32,4 @@ module Puppet::Parser::AbstractCompiler
   def topscope
     raise Puppet::DevError("Class '#{self.class}' should have implemented 'topscope'")
   end
-
 end

data/lib/puppet/parser/ast/block_expression.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # Evaluates contained expressions, produce result of the last
 #
 class Puppet::Parser::AST::BlockExpression < Puppet::Parser::AST::Branch

data/lib/puppet/parser/ast/branch.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # The parent class of all AST objects that contain other AST objects.
 # Everything but the really simple objects descend from this.  It is
 # important to note that Branch objects contain other AST objects only --

data/lib/puppet/parser/ast/hostclass.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative '../../../puppet/parser/ast/top_level_construct'
 
 class Puppet::Parser::AST::Hostclass < Puppet::Parser::AST::TopLevelConstruct

data/lib/puppet/parser/ast/leaf.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
+
 # The base class for all of the leaves of the parse trees.  These
 # basically just have types and values.  Both of these parameters
 # are simple values, not AST objects.
 #
 class Puppet::Parser::AST::Leaf < Puppet::Parser::AST
   attr_accessor :value, :type
+
   # Return our value.
   def evaluate(scope)
     @value

data/lib/puppet/parser/ast/node.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 class Puppet::Parser::AST::Node < Puppet::Parser::AST::TopLevelConstruct
   attr_accessor :names, :context
 

data/lib/puppet/parser/ast/pops_bridge.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative '../../../puppet/parser/ast/top_level_construct'
 require_relative '../../../puppet/pops'
 
@@ -7,7 +8,6 @@ require_relative '../../../puppet/pops'
 # fundamental for the rest of the logic.
 #
 class Puppet::Parser::AST::PopsBridge
-
   # Bridges to one Pops Model Expression
   # The @value is the expression
   # This is used to represent the body of a class, definition, or node, and for each parameter's default value
@@ -66,6 +66,7 @@ class Puppet::Parser::AST::PopsBridge
       end
     end
   end
+
   # Bridges the top level "Program" produced by the pops parser.
   # Its main purpose is to give one point where all definitions are instantiated (actually defined since the
   # Puppet 3x terminology is somewhat misleading - the definitions are instantiated, but instances of the created types
@@ -86,7 +87,6 @@ class Puppet::Parser::AST::PopsBridge
     # efficient as it avoids one full scan of all logic via recursive enumeration/yield)
     #
     def instantiate(modname)
-
       @program_model.definitions.map do |d|
         case d
         when Puppet::Pops::Model::HostClassDefinition
@@ -103,7 +103,7 @@ class Puppet::Parser::AST::PopsBridge
           nil
         end
       end.flatten().compact() # flatten since node definition may have returned an array
-                              # Compact since 4x definitions are not understood by compiler
+      # Compact since 4x definitions are not understood by compiler
     end
 
     def evaluate(scope)
@@ -187,9 +187,9 @@ class Puppet::Parser::AST::PopsBridge
     # Produces a hash with data for Definition and HostClass
     def args_from_definition(o, modname, expr_class = Expression)
       args = {
-       :arguments => o.parameters.collect {|p| instantiate_Parameter(p) },
-       :argument_types => create_type_map(o),
-       :module_name => modname
+        :arguments => o.parameters.collect {|p| instantiate_Parameter(p) },
+        :argument_types => create_type_map(o),
+        :module_name => modname
       }
       unless is_nop?(o.body)
         args[:code] = expr_class.new(:value => o.body)

data/lib/puppet/parser/ast/resource.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
+
 # Instruction for Resource instantiation.
 # Instantiates resources of both native and user defined types.
 #
 class Puppet::Parser::AST::Resource < Puppet::Parser::AST::Branch
-
   attr_accessor :type, :instances, :exported, :virtual
 
   def initialize(argshash)
@@ -26,7 +26,6 @@ class Puppet::Parser::AST::Resource < Puppet::Parser::AST::Branch
     # instance.  This handles things like:
     # file { '/foo': owner => blah; '/bar': owner => blah }
     @instances.map do |instance|
-
       # Evaluate all of the specified params.
       paramobjects = instance.parameters.map { |param| param.safeevaluate(scope) }
 
@@ -43,7 +42,7 @@ class Puppet::Parser::AST::Resource < Puppet::Parser::AST::Branch
       resource_titles.flatten.map do |resource_title|
         exceptwrap :type => Puppet::ParseError do
           resource = Puppet::Parser::Resource.new(
-          fully_qualified_type, resource_title,
+            fully_qualified_type, resource_title,
             :parameters => paramobjects,
             :file => self.file,
             :line => self.line,

data/lib/puppet/parser/ast/resource_instance.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
+
 # A simple container for a parameter for an object.  Consists of a
 # title and a set of parameters.
 #
 class Puppet::Parser::AST::ResourceInstance < Puppet::Parser::AST::Branch
   attr_accessor :title, :parameters
+
   def initialize(argshash)
     Puppet.warn_once('deprecations', 'AST::ResourceInstance', _('Use of Puppet::Parser::AST::ResourceInstance is deprecated'))
     super(argshash)

data/lib/puppet/parser/ast/resourceparam.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # The AST object for the parameters inside resource expressions
 #
 class Puppet::Parser::AST::ResourceParam < Puppet::Parser::AST::Branch
@@ -17,12 +18,12 @@ class Puppet::Parser::AST::ResourceParam < Puppet::Parser::AST::Branch
   def evaluate(scope)
     value = @value.safeevaluate(scope)
     return Puppet::Parser::Resource::Param.new(
-      :name   => @param,
-      :value  => value.nil? ? :undef : value,
+      :name => @param,
+      :value => value.nil? ? :undef : value,
       :source => scope.source, 
-      :line   => self.line,
-      :file   => self.file,
-      :add    => self.add
+      :line => self.line,
+      :file => self.file,
+      :add => self.add
     )
   end
 

data/lib/puppet/parser/ast/top_level_construct.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # The base class for AST nodes representing top level things:
 # hostclasses, definitions, and nodes.
 class Puppet::Parser::AST::TopLevelConstruct < Puppet::Parser::AST

data/lib/puppet/parser/ast.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # The base class for the 3x "parse tree", now only used by the top level
 # constructs and the compiler.
 # Handles things like file name, line #, and also does the initialization
@@ -31,9 +32,9 @@ class Puppet::Parser::AST
       return self.evaluate(scope)
     rescue Puppet::Pops::Evaluator::PuppetStopIteration => detail
       raise detail
-#      # Only deals with StopIteration from the break() function as a general
-#      # StopIteration is a general runtime problem
-#      raise Puppet::ParseError.new(detail.message, detail.file, detail.line, detail)
+    #      # Only deals with StopIteration from the break() function as a general
+    #      # StopIteration is a general runtime problem
+    #      raise Puppet::ParseError.new(detail.message, detail.file, detail.line, detail)
     rescue Puppet::Error => detail
       raise adderrorcontext(detail)
     rescue => detail

data/lib/puppet/parser/catalog_compiler.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative '../../puppet/loaders'
 require_relative '../../puppet/pops'
 
@@ -9,7 +10,6 @@ require_relative '../../puppet/pops'
 # deal with possible errors in a cached environment.
 #
 class Puppet::Parser::CatalogCompiler < Puppet::Parser::Compiler
-
   # Evaluates the configured setup for a script + code in an environment with modules
   #
   def compile
@@ -19,7 +19,6 @@ class Puppet::Parser::CatalogCompiler < Puppet::Parser::Compiler
     Puppet.override(rich_data: true) do
       super
     end
-
   rescue Puppet::ParseErrorWithIssue => detail
     detail.node = node.name
     Puppet.log_exception(detail)

data/lib/puppet/parser/compiler/catalog_validator/relationship_validator.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 class Puppet::Parser::Compiler
   # Validator that asserts relationship metaparameters refer to valid resources
   class CatalogValidator::RelationshipValidator < CatalogValidator
@@ -6,6 +7,7 @@ class Puppet::Parser::Compiler
       catalog.resources.each do |resource|
         next unless resource.is_a?(Puppet::Parser::Resource)
         next if resource.virtual?
+
         resource.eachparam do |param|
           pclass = Puppet::Type.metaparamclass(param.name)
           validate_relationship(param) if !pclass.nil? && pclass < Puppet::Type::RelationshipMetaparam
@@ -21,6 +23,7 @@ class Puppet::Parser::Compiler
       refs = param.value.is_a?(Array) ? param.value.flatten : [param.value]
       refs.each do |r|
         next if r.nil? || r == :undef
+
         res = r.to_s
         begin
           found = catalog.resource(res)

data/lib/puppet/parser/compiler/catalog_validator.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 # Abstract class for a catalog validator that can be registered with the compiler to run at
 # a certain stage.
 class Puppet::Parser::Compiler

data/lib/puppet/parser/compiler.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'forwardable'
 
 require_relative '../../puppet/node'
@@ -79,7 +80,7 @@ class Puppet::Parser::Compiler
     @catalog.add_resource(resource)
 
     if not resource.class? and resource[:stage]
-      #TRANSLATORS "stage" is a keyword in Puppet and should not be translated
+      # TRANSLATORS "stage" is a keyword in Puppet and should not be translated
       raise ArgumentError, _("Only classes can set 'stage'; normal resources like %{resource} cannot change run stage") % { resource: resource }
     end
 
@@ -129,7 +130,7 @@ class Puppet::Parser::Compiler
 
       Puppet::Util::Profiler.profile(_("Compile: Created settings scope"), [:compiler, :create_settings_scope]) { create_settings_scope }
 
-      #TRANSLATORS "main" is a function name and should not be translated
+      # TRANSLATORS "main" is a function name and should not be translated
       Puppet::Util::Profiler.profile(_("Compile: Evaluated main"), [:compiler, :evaluate_main]) { evaluate_main }
 
       Puppet::Util::Profiler.profile(_("Compile: Evaluated AST node"), [:compiler, :evaluate_ast_node]) { evaluate_ast_node }
@@ -166,8 +167,8 @@ class Puppet::Parser::Compiler
   def context_overrides()
     {
       :current_environment => environment,
-      :global_scope => @topscope,             # 4x placeholder for new global scope
-      :loaders  => @loaders,                  # 4x loaders
+      :global_scope => @topscope, # 4x placeholder for new global scope
+      :loaders => @loaders, # 4x loaders
     }
   end
 
@@ -185,7 +186,7 @@ class Puppet::Parser::Compiler
   # parameters won't conflict even if the class has already been included.
   def evaluate_node_classes
     if @node.classes.is_a? Hash
-      classes_with_params, classes_without_params = @node.classes.partition {|name,params| params and !params.empty?}
+      classes_with_params, classes_without_params = @node.classes.partition {|_name,params| params and !params.empty?}
 
       # The results from Hash#partition are arrays of pairs rather than hashes,
       # so we have to convert to the forms evaluate_classes expects (Hash, and
@@ -206,7 +207,7 @@ class Puppet::Parser::Compiler
   # @api private
   def evaluate_ast_node
     krt = environment.known_resource_types
-    return unless krt.nodes? #ast_nodes?
+    return unless krt.nodes? # ast_nodes?
 
     # Now see if we can find the node.
     astnode = nil
@@ -235,6 +236,7 @@ class Puppet::Parser::Compiler
   #
   def evaluate_classes(classes, scope, lazy_evaluate = true)
     raise Puppet::DevError, _("No source for scope passed to evaluate_classes") unless scope.source
+
     class_parameters = nil
     # if we are a param class, save the classes hash
     # and transform classes to be the keys
@@ -349,7 +351,6 @@ class Puppet::Parser::Compiler
             # needs to be handled specifically as the error has the file/line/position where this
             # occurred rather than the resource
             fail(Puppet::Pops::Issues::RUNTIME_ERROR, detail, {:detail => detail.message}, detail)
-
           rescue Puppet::Error => e
             # PuppetError has the ability to wrap an exception, if so, use the wrapped exception's
             # call stack instead
@@ -456,7 +457,7 @@ class Puppet::Parser::Compiler
   def add_resource_metaparams
     main = catalog.resource(:class, :main)
     unless main
-      #TRANSLATORS "main" is a function name and should not be translated
+      # TRANSLATORS "main" is a function name and should not be translated
       raise _("Couldn't find main")
     end
 
@@ -564,6 +565,7 @@ class Puppet::Parser::Compiler
       # case a custom node terminus has done any mucking about with
       # node.parameters.
       next if param.to_s == 'environment'
+
       # Ensure node does not leak Symbol instances in general
       @topscope[param.to_s] = value.is_a?(Symbol) ? value.to_s : value
     end

data/lib/puppet/parser/e4_parser_adapter.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require_relative '../../puppet/pops'
 
 module Puppet
@@ -7,7 +8,6 @@ module Parser
 # and makes use of the new evaluator.
 #
 class E4ParserAdapter
-
   def initialize
     @file = ''
     @string = ''
@@ -23,14 +23,14 @@ class E4ParserAdapter
     self.string= string if string
     parser = Pops::Parser::EvaluatingParser.singleton
     model =
-    if @use == :string
-      # Parse with a source_file to set in created AST objects (it was either given, or it may be unknown
-      # if caller did not set a file and the present a string.
-      #
-      parser.parse_string(@string, @file || "unknown-source-location")
-    else
-      parser.parse_file(@file)
-    end
+      if @use == :string
+        # Parse with a source_file to set in created AST objects (it was either given, or it may be unknown
+        # if caller did not set a file and the present a string.
+        #
+        parser.parse_string(@string, @file || "unknown-source-location")
+      else
+        parser.parse_file(@file)
+      end
 
     # the parse_result may be
     # * empty / nil (no input)
@@ -41,12 +41,12 @@ class E4ParserAdapter
     Pops::Model::AstTransformer.new(@file).merge_location(args, model)
 
     ast_code =
-    if model.is_a? Pops::Model::Program
-      AST::PopsBridge::Program.new(model, args)
-    else
-      args[:value] = model
-      AST::PopsBridge::Expression.new(args)
-    end
+      if model.is_a? Pops::Model::Program
+        AST::PopsBridge::Program.new(model, args)
+      else
+        args[:value] = model
+        AST::PopsBridge::Expression.new(args)
+      end
 
     # Create the "main" class for the content - this content will get merged with all other "main" content
     AST::Hostclass.new('', :code => ast_code)

data/lib/puppet/parser/files.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
-module Puppet::Parser::Files
 
+module Puppet::Parser::Files
   module_function
 
   # Return a list of manifests as absolute filenames matching the given

data/lib/puppet/parser/functions/assert_type.rb

@@ -1,61 +1,62 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :assert_type,
   :type => :rvalue,
   :arity => -3,
-  :doc => <<DOC
-Returns the given value if it is of the given
-[data type](https://puppet.com/docs/puppet/latest/lang_data.html), or
-otherwise either raises an error or executes an optional two-parameter
-[lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html).
-
-The function takes two mandatory arguments, in this order:
-
-1. The expected data type.
-2. A value to compare against the expected data type.
-
-**Example**: Using `assert_type`
-
-~~~ puppet
-$raw_username = 'Amy Berry'
-
-# Assert that $raw_username is a non-empty string and assign it to $valid_username.
-$valid_username = assert_type(String[1], $raw_username)
-
-# $valid_username contains "Amy Berry".
-# If $raw_username was an empty string or a different data type, the Puppet run would
-# fail with an "Expected type does not match actual" error.
-~~~
-
-You can use an optional lambda to provide enhanced feedback. The lambda takes two
-mandatory parameters, in this order:
-
-1. The expected data type as described in the function's first argument.
-2. The actual data type of the value.
-
-**Example**: Using `assert_type` with a warning and default value
-
-~~~ puppet
-$raw_username = 'Amy Berry'
-
-# Assert that $raw_username is a non-empty string and assign it to $valid_username.
-# If it isn't, output a warning describing the problem and use a default value.
-$valid_username = assert_type(String[1], $raw_username) |$expected, $actual| {
-  warning( "The username should be \'${expected}\', not \'${actual}\'. Using 'anonymous'." )
-  'anonymous'
-}
-
-# $valid_username contains "Amy Berry".
-# If $raw_username was an empty string, the Puppet run would set $valid_username to
-# "anonymous" and output a warning: "The username should be 'String[1, default]', not
-# 'String[0, 0]'. Using 'anonymous'."
-~~~
-
-For more information about data types, see the
-[documentation](https://puppet.com/docs/puppet/latest/lang_data.html).
-
-- Since 4.0.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Returns the given value if it is of the given
+    [data type](https://puppet.com/docs/puppet/latest/lang_data.html), or
+    otherwise either raises an error or executes an optional two-parameter
+    [lambda](https://puppet.com/docs/puppet/latest/lang_lambdas.html).
+    
+    The function takes two mandatory arguments, in this order:
+    
+    1. The expected data type.
+    2. A value to compare against the expected data type.
+    
+    **Example**: Using `assert_type`
+    
+    ~~~ puppet
+    $raw_username = 'Amy Berry'
+    
+    # Assert that $raw_username is a non-empty string and assign it to $valid_username.
+    $valid_username = assert_type(String[1], $raw_username)
+    
+    # $valid_username contains "Amy Berry".
+    # If $raw_username was an empty string or a different data type, the Puppet run would
+    # fail with an "Expected type does not match actual" error.
+    ~~~
+    
+    You can use an optional lambda to provide enhanced feedback. The lambda takes two
+    mandatory parameters, in this order:
+    
+    1. The expected data type as described in the function's first argument.
+    2. The actual data type of the value.
+    
+    **Example**: Using `assert_type` with a warning and default value
+    
+    ~~~ puppet
+    $raw_username = 'Amy Berry'
+    
+    # Assert that $raw_username is a non-empty string and assign it to $valid_username.
+    # If it isn't, output a warning describing the problem and use a default value.
+    $valid_username = assert_type(String[1], $raw_username) |$expected, $actual| {
+      warning( "The username should be \'${expected}\', not \'${actual}\'. Using 'anonymous'." )
+      'anonymous'
+    }
+    
+    # $valid_username contains "Amy Berry".
+    # If $raw_username was an empty string, the Puppet run would set $valid_username to
+    # "anonymous" and output a warning: "The username should be 'String[1, default]', not
+    # 'String[0, 0]'. Using 'anonymous'."
+    ~~~
+    
+    For more information about data types, see the
+    [documentation](https://puppet.com/docs/puppet/latest/lang_data.html).
+    
+    - Since 4.0.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('assert_type')
 end

data/lib/puppet/parser/functions/binary_file.rb

@@ -1,25 +1,26 @@
 # frozen_string_literal: true
+
 Puppet::Parser::Functions::newfunction(
   :binary_file,
   :type => :rvalue,
   :arity => 1,
-:doc => <<-DOC
-Loads a binary file from a module or file system and returns its contents as a Binary.
-
-The argument to this function should be a `<MODULE NAME>/<FILE>`
-reference, which will load `<FILE>` from a module's `files`
-directory. (For example, the reference `mysql/mysqltuner.pl` will load the
-file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
-
-This function also accepts an absolute file path that allows reading
-binary file content from anywhere on disk.
-
-An error is raised if the given file does not exists.
-
-To search for the existence of files, use the `find_file()` function.
-
-- since 4.8.0
-DOC
-) do |args|
+  :doc => <<~DOC
+    Loads a binary file from a module or file system and returns its contents as a Binary.
+    
+    The argument to this function should be a `<MODULE NAME>/<FILE>`
+    reference, which will load `<FILE>` from a module's `files`
+    directory. (For example, the reference `mysql/mysqltuner.pl` will load the
+    file `<MODULES DIRECTORY>/mysql/files/mysqltuner.pl`.)
+    
+    This function also accepts an absolute file path that allows reading
+    binary file content from anywhere on disk.
+    
+    An error is raised if the given file does not exists.
+    
+    To search for the existence of files, use the `find_file()` function.
+    
+    - since 4.8.0
+  DOC
+) do |_args|
   Puppet::Parser::Functions::Error.is4x('binary_file')
 end