puppet-strings 2.4.0 → 2.8.0

data/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb

@@ -1,309 +0,0 @@
-require 'spec_helper'
-require 'puppet-strings/yard'
-
-describe PuppetStrings::Yard::Handlers::Ruby::DataTypeHandler, if: TEST_PUPPET_DATATYPES do
-  subject {
-    YARD::Parser::SourceParser.parse_string(source, :ruby)
-    YARD::Registry.all(:puppet_data_type)
-  }
-
-  before(:each) do
-    # Tests may suppress logging to make it easier to read results,
-    # so remember the logging object prior to running the test
-    @original_yard_logging_object = YARD::Logger.instance.io
-  end
-
-  after(:each) do
-    # Restore the original logging IO object
-    YARD::Logger.instance.io = @original_yard_logging_object
-  end
-
-  def suppress_yard_logging
-    YARD::Logger.instance.io = nil
-  end
-
-  describe 'parsing source without a data type definition' do
-    let(:source) { 'puts "hi"' }
-
-    it 'no data types should be in the registry' do
-      expect(subject.empty?).to eq(true)
-    end
-  end
-
-  describe 'parsing an empty data type definition' do
-    let(:source) { <<-SOURCE
-Puppet::DataTypes.create_type('RubyDataType') do
-end
-SOURCE
-    }
-
-    it 'should register a data type object with no param tags' do
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
-      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
-      expect(object.name).to eq(:RubyDataType)
-      expect(object.docstring).to eq('')
-      expect(object.docstring.tags.size).to eq(1)
-      tags = object.docstring.tags(:api)
-      expect(tags.size).to eq(1)
-      expect(tags[0].text).to eq('public')
-
-      expect(object.parameters.size).to eq(0)
-    end
-  end
-
-  describe 'parsing a data type definition with missing param tags' do
-    let(:source) { <<-SOURCE
-# An example Puppet Data Type in Ruby.
-Puppet::DataTypes.create_type('RubyDataType') do
-  interface <<-PUPPET
-    attributes => {
-      msg => String[1],
-    }
-    PUPPET
-end
-SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: Missing @param tag for attribute 'msg' near \(stdin\):2/).to_stdout_from_any_process
-    end
-
-    it 'should register a data type object with all param tags' do
-      suppress_yard_logging
-
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
-      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
-      expect(object.name).to eq(:RubyDataType)
-      expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
-      expect(object.docstring.tags.size).to eq(2)
-      tags = object.docstring.tags(:api)
-      expect(tags.size).to eq(1)
-      expect(tags[0].text).to eq('public')
-
-      # Check that the param tags are created
-      tags = object.docstring.tags(:param)
-      expect(tags.size).to eq(1)
-      expect(tags[0].name).to eq('msg')
-      expect(tags[0].text).to eq('')
-      expect(tags[0].types).to eq(['String[1]'])
-
-      # Check for default values for parameters
-      expect(object.parameters.size).to eq(1)
-      expect(object.parameters[0]).to eq(['msg', nil])
-    end
-  end
-
-  describe 'parsing a data type definition with extra param tags' do
-    let(:source) { <<-SOURCE
-# An example Puppet Data Type in Ruby.
-# @param msg A message parameter.
-# @param arg1 Optional String parameter. Defaults to 'param'.
-Puppet::DataTypes.create_type('RubyDataType') do
-  interface <<-PUPPET
-    attributes => {
-      msg => Numeric,
-    }
-    PUPPET
-end
-SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The @param tag for 'arg1' has no matching attribute near \(stdin\):4/).to_stdout_from_any_process
-    end
-
-    it 'should register a data type object with extra param tags removed' do
-      suppress_yard_logging
-
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
-      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
-      expect(object.name).to eq(:RubyDataType)
-      expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
-      expect(object.docstring.tags.size).to eq(2)
-      tags = object.docstring.tags(:api)
-      expect(tags.size).to eq(1)
-      expect(tags[0].text).to eq('public')
-
-      # Check that the param tags are removed
-      tags = object.docstring.tags(:param)
-      expect(tags.size).to eq(1)
-      expect(tags[0].name).to eq('msg')
-      expect(tags[0].text).to eq('A message parameter.')
-      expect(tags[0].types).to eq(['Numeric'])
-
-      # Check that only the actual attributes appear
-      expect(object.parameters.size).to eq(1)
-      expect(object.parameters[0]).to eq(['msg', nil])
-    end
-  end
-
-  describe 'parsing a valid data type definition' do
-    let(:source) { <<-SOURCE
-# An example Puppet Data Type in Ruby.
-#
-# @param msg A message parameter5.
-# @param arg1 Optional String parameter5. Defaults to 'param'.
-Puppet::DataTypes.create_type('RubyDataType') do
-  interface <<-PUPPET
-    attributes => {
-      msg   => Variant[Numeric, String[1,2]],
-      arg1  => { type => Optional[String[1]], value => "param" }
-    }
-    PUPPET
-end
-SOURCE
-    }
-
-    it 'should register a data type object' do
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
-      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
-      expect(object.name).to eq(:RubyDataType)
-      expect(object.docstring).to eq('An example Puppet Data Type in Ruby.')
-      expect(object.docstring.tags.size).to eq(3)
-      tags = object.docstring.tags(:api)
-      expect(tags.size).to eq(1)
-      expect(tags[0].text).to eq('public')
-
-      # Check that the param tags are removed
-      tags = object.docstring.tags(:param)
-      expect(tags.size).to eq(2)
-      expect(tags[0].name).to eq('msg')
-      expect(tags[0].text).to eq('A message parameter5.')
-      expect(tags[0].types).to eq(['Variant[Numeric, String[1,2]]'])
-      expect(tags[1].name).to eq('arg1')
-      expect(tags[1].text).to eq('Optional String parameter5. Defaults to \'param\'.')
-      expect(tags[1].types).to eq(['Optional[String[1]]'])
-
-      # Check for default values
-      expect(object.parameters.size).to eq(2)
-      expect(object.parameters[0]).to eq(['msg', nil])
-      expect(object.parameters[1]).to eq(['arg1', 'param'])
-    end
-  end
-
-  testcases = [
-    { :value => '-1', :expected => -1 },
-    { :value => '0', :expected => 0 },
-    { :value => '10', :expected => 10 },
-    { :value => '0777', :expected => 511 },
-    { :value => '0xFF', :expected => 255 },
-    { :value => '0.1', :expected => 0.1 },
-    { :value => '31.415e-1', :expected => 3.1415 },
-    { :value => '0.31415e1', :expected => 3.1415 }
-  ].each do |testcase|
-    describe "parsing a valid data type definition with numeric default #{testcase[:value]}" do
-      let(:source) { <<-SOURCE
-# An example Puppet Data Type in Ruby.
-# @param num1 A numeric parameter
-Puppet::DataTypes.create_type('RubyDataType') do
-  interface <<-PUPPET
-    attributes => {
-      num1 => { type => Numeric, value => #{testcase[:value]} },
-    }
-    PUPPET
-end
-SOURCE
-      }
-
-      it 'should register a data type object' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
-        expect(object.parameters.size).to eq(1)
-        expect(object.parameters[0]).to eq(['num1', testcase[:expected]])
-      end
-    end
-  end
-
-  describe 'parsing a invalid data type definition' do
-    let(:source) { <<-SOURCE
-# The msg attribute is missing a comma.
-#
-# @param msg A message parameter5.
-# @param arg1 Optional String parameter5. Defaults to 'param'.
-Puppet::DataTypes.create_type('RubyDataType') do
-  interface <<-PUPPET
-    attributes => {
-      msg   => Variant[Numeric, String[1,2]]
-      arg1  => { type => Optional[String[1]], value => "param" }
-    }
-    PUPPET
-end
-SOURCE
-    }
-
-    it 'should register a partial data type object' do
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::DataType)
-      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::DataTypes.instance)
-      expect(object.name).to eq(:RubyDataType)
-      expect(object.docstring).to eq('The msg attribute is missing a comma.')
-      # The attributes will be missing therefore only one tag
-      expect(object.docstring.tags.size).to eq(1)
-      tags = object.docstring.tags(:api)
-      expect(tags.size).to eq(1)
-      expect(tags[0].text).to eq('public')
-
-      # Check that the param tags are removed
-      tags = object.docstring.tags(:param)
-      expect(tags.size).to eq(0)
-
-      # Check for default values
-      expect(object.parameters.size).to eq(0)
-    end
-
-    it 'should log a warning' do
-      expect{ subject }.to output(/\[warn\]: Invalid datatype definition at (.+):[0-9]+: Syntax error at 'arg1'/).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a data type with a summary' do
-    context 'when the summary has fewer than 140 characters' do
-      let(:source) { <<-SOURCE
-# An example Puppet Data Type in Ruby.
-#
-# @summary A short summary.
-Puppet::DataTypes.create_type('RubyDataType') do
-  interface <<-PUPPET
-    attributes => { }
-    PUPPET
-end
-SOURCE
-      }
-
-      it 'should parse the summary' do
-        expect{ subject }.to output('').to_stdout_from_any_process
-        expect(subject.size).to eq(1)
-        summary = subject.first.tags(:summary)
-        expect(summary.first.text).to eq('A short summary.')
-      end
-    end
-
-    context 'when the summary has more than 140 characters' do
-      let(:source) { <<-SOURCE
-# An example Puppet Data Type in Ruby.
-#
-# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
-Puppet::DataTypes.create_type('RubyDataType') do
-  interface <<-PUPPET
-    attributes => { }
-    PUPPET
-end
-SOURCE
-      }
-
-      it 'should log a warning' do
-        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_data_type 'RubyDataType' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
-      end
-    end
-  end
-end

data/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb

@@ -1,746 +0,0 @@
-require 'spec_helper'
-require 'puppet-strings/yard'
-
-describe PuppetStrings::Yard::Handlers::Ruby::FunctionHandler do
-  subject {
-    YARD::Parser::SourceParser.parse_string(source, :ruby)
-    YARD::Registry.all(:puppet_function)
-  }
-
-  describe 'parsing source without a function definition' do
-    let(:source) { 'puts "hi"' }
-
-    it 'no functions should be in the registry' do
-      expect(subject.empty?).to eq(true)
-    end
-  end
-
-  describe 'parsing 3.x API functions' do
-    describe 'parsing a function with a missing docstring' do
-      let(:source) { <<-SOURCE
-Puppet::Parser::Functions.newfunction(:foo) do |*args|
-end
-      SOURCE
-      }
-
-      it 'should log a warning' do
-        expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process
-      end
-    end
-
-    describe 'parsing a function with a doc parameter' do
-      let(:source) { <<-SOURCE
-Puppet::Parser::Functions.newfunction(:foo, doc: <<-DOC
-An example 3.x function.
-@param [String] first The first parameter.
-@param second The second parameter.
-@return [Undef] Returns nothing.
-DOC
-) do |*args|
-end
-      SOURCE
-      }
-
-      it 'should register a function object' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_3X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(String $first, Any $second)')
-        expect(object.parameters).to eq([['first', nil], ['second', nil]])
-        expect(object.docstring).to eq('An example 3.x function.')
-        expect(object.docstring.tags.size).to eq(4)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(2)
-        expect(tags[0].name).to eq('first')
-        expect(tags[0].text).to eq('The first parameter.')
-        expect(tags[0].types).to eq(['String'])
-        expect(tags[1].name).to eq('second')
-        expect(tags[1].text).to eq('The second parameter.')
-        expect(tags[1].types).to eq(['Any'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function with a doc parameter which has a newline between the namespace and the newfunction call' do
-      let(:source) { <<-SOURCE
-module Puppet::Parser::Functions
-  newfunction(:foo, doc: <<-DOC
-An example 3.x function.
-@param [String] first The first parameter.
-@param second The second parameter.
-@return [Undef] Returns nothing.
-DOC
-) do |*args|
-  end
-end
-      SOURCE
-      }
-
-      it 'should register a function object' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_3X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(String $first, Any $second)')
-        expect(object.parameters).to eq([['first', nil], ['second', nil]])
-        expect(object.docstring).to eq('An example 3.x function.')
-        expect(object.docstring.tags.size).to eq(4)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(2)
-        expect(tags[0].name).to eq('first')
-        expect(tags[0].text).to eq('The first parameter.')
-        expect(tags[0].types).to eq(['String'])
-        expect(tags[1].name).to eq('second')
-        expect(tags[1].text).to eq('The second parameter.')
-        expect(tags[1].types).to eq(['Any'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function with a missing @return tag' do
-      let(:source) { <<-SOURCE
-Puppet::Parser::Functions.newfunction(:foo, doc: <<-DOC) do |*args|
-An example 3.x function.
-@param [String] first The first parameter.
-@param second The second parameter.
-DOC
-end
-      SOURCE
-      }
-
-      it 'should log a warning' do
-        expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):1/).to_stdout_from_any_process
-      end
-    end
-  end
-
-  describe 'parsing 4.x API functions' do
-    describe 'parsing a function with a missing docstring' do
-      let(:source) { <<-SOURCE
-Puppet::Functions.create_function(:foo) do
-end
-      SOURCE
-      }
-
-      it 'should log a warning' do
-        expect{ subject }.to output(/\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\./).to_stdout_from_any_process
-      end
-    end
-
-    describe 'parsing a function with a simple docstring' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-end
-      SOURCE
-      }
-
-      it 'should register a function object' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo()')
-        expect(object.parameters).to eq([])
-        expect(object.docstring).to eq('An example 4.x function.')
-        expect(object.docstring.tags.size).to eq(1)
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function without any dispatches' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param [Integer] param1 The first parameter.
-  # @param param2 The second parameter.
-  # @param [String] param3 The third parameter.
-  # @return [Undef] Returns nothing.
-  def foo(param1, param2, param3 = nil)
-  end
-end
-      SOURCE
-      }
-
-      it 'should register a function object' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(Integer $param1, Any $param2, Optional[String] $param3 = undef)')
-        expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'undef']])
-        expect(object.docstring).to eq('An example 4.x function.')
-        expect(object.docstring.tags.size).to eq(5)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(3)
-        expect(tags[0].name).to eq('param1')
-        expect(tags[0].text).to eq('The first parameter.')
-        expect(tags[0].types).to eq(['Integer'])
-        expect(tags[1].name).to eq('param2')
-        expect(tags[1].text).to eq('The second parameter.')
-        expect(tags[1].types).to eq(['Any'])
-        expect(tags[2].name).to eq('param3')
-        expect(tags[2].text).to eq('The third parameter.')
-        expect(tags[2].types).to eq(['Optional[String]'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function with a single dispatch' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param param1 The first parameter.
-  # @param param2 The second parameter.
-  # @param param3 The third parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    param          'Integer',       :param1
-    param          'Any',           :param2
-    optional_param 'Array[String]', :param3
-  end
-
-  def foo(param1, param2, param3 = nil)
-  end
-end
-      SOURCE
-      }
-
-      it 'should register a function object without any overload tags' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(Integer $param1, Any $param2, Optional[Array[String]] $param3)')
-        expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', nil]])
-        expect(object.docstring).to eq('An example 4.x function.')
-        expect(object.docstring.tags(:overload).empty?).to be_truthy
-        expect(object.docstring.tags.size).to eq(5)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(3)
-        expect(tags[0].name).to eq('param1')
-        expect(tags[0].text).to eq('The first parameter.')
-        expect(tags[0].types).to eq(['Integer'])
-        expect(tags[1].name).to eq('param2')
-        expect(tags[1].text).to eq('The second parameter.')
-        expect(tags[1].types).to eq(['Any'])
-        expect(tags[2].name).to eq('param3')
-        expect(tags[2].text).to eq('The third parameter.')
-        expect(tags[2].types).to eq(['Optional[Array[String]]'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function using only return_type' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param param1 The first parameter.
-  # @param param2 The second parameter.
-  # @param param3 The third parameter.
-  dispatch :foo do
-    param          'Integer',       :param1
-    param          'Any',           :param2
-    optional_param 'Array[String]', :param3
-    return_type 'String'
-  end
-
-  def foo(param1, param2, param3 = nil)
-    "Bar"
-  end
-end
-      SOURCE
-      }
-
-      it 'does not throw an error with no @return' do
-        expect { subject }.not_to raise_error
-      end
-
-      it 'contains a return data type' do
-        tags = subject.first.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].types).to eq(['String'])
-      end
-    end
-
-    describe 'parsing a function with various dispatch parameters.' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param param1 The first parameter.
-  # @param param2 The second parameter.
-  # @param param3 The third parameter.
-  # @param param4 The fourth parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    param          'String',  :param1
-    required_param 'Integer', :param2
-    optional_param 'Array',   :param3
-    repeated_param 'String',  :param4
-  end
-end
-      SOURCE
-      }
-
-      it 'should register a function object with the expected parameters' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(String $param1, Integer $param2, Optional[Array] $param3, String *$param4)')
-        expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', nil], ['*param4', nil]])
-        expect(object.docstring).to eq('An example 4.x function.')
-        expect(object.docstring.tags(:overload).empty?).to be_truthy
-        expect(object.docstring.tags.size).to eq(6)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(4)
-        expect(tags[0].name).to eq('param1')
-        expect(tags[0].text).to eq('The first parameter.')
-        expect(tags[0].types).to eq(['String'])
-        expect(tags[1].name).to eq('param2')
-        expect(tags[1].text).to eq('The second parameter.')
-        expect(tags[1].types).to eq(['Integer'])
-        expect(tags[2].name).to eq('param3')
-        expect(tags[2].text).to eq('The third parameter.')
-        expect(tags[2].types).to eq(['Optional[Array]'])
-        expect(tags[3].name).to eq('*param4')
-        expect(tags[3].text).to eq('The fourth parameter.')
-        expect(tags[3].types).to eq(['String'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function with an optional repeated param.' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param param The first parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    optional_repeated_param 'String',  :param
-  end
-end
-      SOURCE
-      }
-
-      it 'should register a function object with the expected parameters' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(Optional[String] *$param)')
-        expect(object.parameters).to eq([['*param', nil]])
-        expect(object.docstring).to eq('An example 4.x function.')
-        expect(object.docstring.tags(:overload).empty?).to be_truthy
-        expect(object.docstring.tags.size).to eq(3)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to eq('*param')
-        expect(tags[0].text).to eq('The first parameter.')
-        expect(tags[0].types).to eq(['Optional[String]'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function with a block param with one parameter' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param a_block The block parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    block_param :a_block
-  end
-end
-      SOURCE
-      }
-
-      it 'should register a function object with the expected parameters' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(Callable &$a_block)')
-        expect(object.parameters).to eq([['&a_block', nil]])
-        expect(object.docstring).to eq('An example 4.x function.')
-        expect(object.docstring.tags(:overload).empty?).to be_truthy
-        expect(object.docstring.tags.size).to eq(3)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to eq('&a_block')
-        expect(tags[0].text).to eq('The block parameter.')
-        expect(tags[0].types).to eq(['Callable'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-
-    describe 'parsing a function with a block param with two parameter' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param a_block The block parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    optional_block_param 'Callable[String]', :a_block
-  end
-end
-      SOURCE
-      }
-
-      it 'should register a function object with the expected parameters' do
-        expect(subject.size).to eq(1)
-        object = subject.first
-        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-        expect(object.name).to eq(:foo)
-        expect(object.signature).to eq('foo(Optional[Callable[String]] &$a_block)')
-        expect(object.parameters).to eq([['&a_block', nil]])
-        expect(object.docstring).to eq('An example 4.x function.')
-        expect(object.docstring.tags(:overload).empty?).to be_truthy
-        expect(object.docstring.tags.size).to eq(3)
-        tags = object.docstring.tags(:param)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to eq('&a_block')
-        expect(tags[0].text).to eq('The block parameter.')
-        expect(tags[0].types).to eq(['Optional[Callable[String]]'])
-        tags = object.docstring.tags(:return)
-        expect(tags.size).to eq(1)
-        expect(tags[0].name).to be_nil
-        expect(tags[0].text).to eq('Returns nothing.')
-        expect(tags[0].types).to eq(['Undef'])
-        tags = object.docstring.tags(:api)
-        expect(tags.size).to eq(1)
-        expect(tags[0].text).to eq('public')
-      end
-    end
-  end
-
-  describe 'parsing a function with a multiple dispatches' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # The first overload.
-  # @param param1 The first parameter.
-  # @param param2 The second parameter.
-  # @param param3 The third parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    param          'Integer',       :param1
-    param          'Any',           :param2
-    optional_param 'Array[String]', :param3
-  end
-
-  # The second overload.
-  # @param param The first parameter.
-  # @param block The block parameter.
-  # @return [String] Returns a string.
-  dispatch :other do
-    param 'Boolean', :param
-    block_param
-  end
-
-  def foo(param1, param2, param3 = nil)
-  end
-
-  def other(b)
-    'lol'
-  end
-end
-    SOURCE
-    }
-
-    it 'should register a function object with overload tags' do
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_4X))
-      expect(object.name).to eq(:foo)
-      expect(object.signature).to eq('')
-      expect(object.parameters).to eq([])
-      expect(object.docstring).to eq('An example 4.x function.')
-      expect(object.docstring.tags(:param).empty?).to be_truthy
-      expect(object.docstring.tags(:return).empty?).to be_truthy
-      expect(object.docstring.tags.size).to eq(3)
-      overloads = object.docstring.tags(:overload)
-      expect(overloads.size).to eq(2)
-      expect(overloads[0]).to be_a(PuppetStrings::Yard::Tags::OverloadTag)
-      expect(overloads[0].docstring).to eq('The first overload.')
-      expect(overloads[0].signature).to eq('foo(Integer $param1, Any $param2, Optional[Array[String]] $param3)')
-      expect(overloads[0].tags.size).to eq(4)
-      tags = overloads[0].tags(:param)
-      expect(tags.size).to eq(3)
-      expect(tags[0].name).to eq('param1')
-      expect(tags[0].text).to eq('The first parameter.')
-      expect(tags[0].types).to eq(['Integer'])
-      expect(tags[1].name).to eq('param2')
-      expect(tags[1].text).to eq('The second parameter.')
-      expect(tags[1].types).to eq(['Any'])
-      expect(tags[2].name).to eq('param3')
-      expect(tags[2].text).to eq('The third parameter.')
-      expect(tags[2].types).to eq(['Optional[Array[String]]'])
-      tags = overloads[0].tags(:return)
-      expect(tags.size).to eq(1)
-      expect(tags[0].name).to be_nil
-      expect(tags[0].text).to eq('Returns nothing.')
-      expect(tags[0].types).to eq(['Undef'])
-      expect(overloads[1]).to be_a(PuppetStrings::Yard::Tags::OverloadTag)
-      expect(overloads[1].docstring).to eq('The second overload.')
-      expect(overloads[1].signature).to eq('foo(Boolean $param, Callable &$block)')
-      expect(overloads[1].tags.size).to eq(3)
-      tags = overloads[1].tags(:param)
-      expect(tags.size).to eq(2)
-      expect(tags[0].name).to eq('param')
-      expect(tags[0].text).to eq('The first parameter.')
-      expect(tags[0].types).to eq(['Boolean'])
-      expect(tags[1].name).to eq('&block')
-      expect(tags[1].text).to eq('The block parameter.')
-      expect(tags[1].types).to eq(['Callable'])
-      tags = overloads[1].tags(:return)
-      expect(tags.size).to eq(1)
-      expect(tags[0].name).to be_nil
-      expect(tags[0].text).to eq('Returns a string.')
-      expect(tags[0].types).to eq(['String'])
-      tags = object.docstring.tags(:api)
-      expect(tags.size).to eq(1)
-      expect(tags[0].text).to eq('public')
-    end
-  end
-
-  describe 'parsing a function with a namespaced name' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:'foo::bar::baz') do
-  # @return [Undef]
-  dispatch :foo do
-  end
-end
-    SOURCE
-    }
-
-    it 'should output the name correctly as a symbol' do
-      expect(subject.size).to eq(1)
-      expect(subject.first.name).to eq(:'foo::bar::baz')
-    end
-  end
-
-  describe 'parsing a function with a missing parameter' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param missing A missing parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-  end
-end
-    SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'missing' has no matching parameter at \(stdin\):5/).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a missing @param tag' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    param 'String', :param1
-  end
-end
-    SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param1' near \(stdin\):5/).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a typed @param tag' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param [Integer] param1 The first parameter.
-  # @return [Undef] Returns nothing.
-  dispatch :foo do
-    param 'String', :param1
-  end
-end
-    SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param1' should not contain a type specification near \(stdin\):6: ignoring in favor of dispatch type information\./).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a typed @param tag' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-Puppet::Functions.create_function(:foo) do
-  # @param param1 The first parameter.
-  dispatch :foo do
-    param 'String', :param1
-  end
-end
-    SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):4/).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a root @param tag' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-# @param param Nope.
-Puppet::Functions.create_function(:foo) do
-  # @return [Undef]
-  dispatch :foo do
-  end
-end
-    SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @param tags near \(stdin\):3: parameter documentation should be made on the dispatch call\./).to_stdout_from_any_process
-    end
-  end
-
-
-  describe 'parsing a function with a root @overload tag' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-# @overload foo
-Puppet::Functions.create_function(:foo) do
-  # @return [Undef]
-  dispatch :foo do
-  end
-end
-    SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @overload tags near \(stdin\):3: overload tags are automatically generated from the dispatch calls\./).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a root @return tag' do
-    let(:source) { <<-SOURCE
-# An example 4.x function.
-# @return [Undef] foo
-Puppet::Functions.create_function(:foo) do
-  # @return [Undef]
-  dispatch :foo do
-  end
-end
-    SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The docstring for Puppet 4.x function 'foo' contains @return tags near \(stdin\):3: return value documentation should be made on the dispatch call\./).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a summary' do
-    context 'when the summary has fewer than 140 characters' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-# @summary A short summary.
-Puppet::Functions.create_function(:foo) do
-  # @return [Undef]
-  dispatch :foo do
-  end
-end
-      SOURCE
-      }
-
-      it 'should parse the summary' do
-        expect{ subject }.to output('').to_stdout_from_any_process
-        expect(subject.size).to eq(1)
-        summary = subject.first.tags(:summary)
-        expect(summary.first.text).to eq('A short summary.')
-      end
-    end
-
-    context 'when the summary has more than 140 characters' do
-      let(:source) { <<-SOURCE
-# An example 4.x function.
-# @summary A short summary that is WAY TOO LONG. AHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHHH this is not what a summary is for! It should be fewer than 140 characters!!
-Puppet::Functions.create_function(:foo) do
-  # @return [Undef]
-  dispatch :foo do
-  end
-end
-      SOURCE
-      }
-
-      it 'should log a warning' do
-        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
-      end
-    end
-  end
-end