puppet-strings 2.2.0 → 2.6.0

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

@@ -1,315 +0,0 @@
-require 'spec_helper'
-require 'puppet-strings/yard'
-
-# Limit this spec to Puppet 4.1+ (when functions in Puppet were implemented)
-describe PuppetStrings::Yard::Handlers::Puppet::FunctionHandler, if: TEST_PUPPET_FUNCTIONS do
-  subject {
-    YARD::Parser::SourceParser.parse_string(source, :puppet)
-    YARD::Registry.all(:puppet_function)
-  }
-
-  describe 'parsing source without a function definition' do
-    let(:source) { 'notice hi' }
-
-    it 'no functions should be in the registry' do
-      expect(subject.empty?).to eq(true)
-    end
-  end
-
-  describe 'parsing source with a syntax error' do
-    let(:source) { 'function foo{' }
-
-    it 'should log an error' do
-      expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of/).to_stdout_from_any_process
-      expect(subject.empty?).to eq(true)
-    end
-  end
-
-  describe 'parsing a function with a missing docstring' do
-    let(:source) { 'function foo{}' }
-
-    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 docstring' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @param param1 First param.
-# @param param2 Second param.
-# @param param3 Third param.
-# @return [Undef] Returns nothing.
-function foo(Integer $param1, $param2, String $param3 = hi) {
-  notice 'hello world'
-  undef
-}
-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::PUPPET))
-      expect(object.name).to eq(:foo)
-      expect(object.signature).to eq('foo(Integer $param1, Any $param2, String $param3 = hi)')
-      expect(object.parameters).to eq([['param1', nil], ['param2', nil], ['param3', 'hi']])
-      expect(object.docstring).to eq('A simple foo 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('First param.')
-      expect(tags[0].types).to eq(['Integer'])
-      expect(tags[1].name).to eq('param2')
-      expect(tags[1].text).to eq('Second param.')
-      expect(tags[1].types).to eq(['Any'])
-      expect(tags[2].name).to eq('param3')
-      expect(tags[2].text).to eq('Third param.')
-      expect(tags[2].types).to eq(['String'])
-      tags = object.docstring.tags(:return)
-      expect(tags.size).to eq(1)
-      expect(tags[0].tag_name).to eq('return')
-      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 parameter' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @param param1 First param.
-# @param param2 Second param.
-# @param param3 Third param.
-# @param param4 missing!
-# @return [Undef] Returns nothing.
-function foo(Integer $param1, $param2, String $param3 = hi) {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):7\./).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a missing @param tag' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @param param1 First param.
-# @param param2 Second param.
-# @return [Undef] Returns nothing.
-function foo(Integer $param1, $param2, String $param3 = hi) {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):5\./).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a typed parameter that also has a @param tag type which matches' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @param [Integer] param1 First param.
-# @param param2 Second param.
-# @param param3 Third param.
-# @return [Undef] Returns nothing.
-function foo(Integer $param1, $param2, String $param3 = hi) {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should respect the type that was documented' do
-      expect{ subject }.to output('').to_stdout_from_any_process
-      expect(subject.size).to eq(1)
-      tags = subject.first.tags(:param)
-      expect(tags.size).to eq(3)
-      expect(tags[0].types).to eq(['Integer'])
-    end
-  end
-
-  describe 'parsing a function with a typed parameter that also has a @param tag type which does not match' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @param [Boolean] param1 First param.
-# @param param2 Second param.
-# @param param3 Third param.
-# @return [Undef] Returns nothing.
-function foo(Integer $param1, $param2, String $param3 = hi) {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: The type of the @param tag for parameter 'param1' does not match the parameter type specification near \(stdin\):6: ignoring in favor of parameter type information./).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a untyped parameter that also has a @param tag type' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @param param1 First param.
-# @param [Boolean] param2 Second param.
-# @param param3 Third param.
-# @return [Undef] Returns nothing.
-function foo(Integer $param1, $param2, String $param3 = hi) {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should respect the type that was documented' do
-      expect{ subject }.to output('').to_stdout_from_any_process
-      expect(subject.size).to eq(1)
-      tags = subject.first.tags(:param)
-      expect(tags.size).to eq(3)
-      expect(tags[1].types).to eq(['Boolean'])
-    end
-  end
-
-  describe 'parsing a function with a missing @return tag' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @param param1 First param.
-# @param param2 Second param.
-# @param param3 Third param.
-function foo(Integer $param1, $param2, String $param3 = hi) {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should output a warning' do
-      expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):5\./).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a missing @return tag and return type specified in the function definition', if: TEST_FUNCTION_RETURN_TYPE do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-function foo() >> String {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should register a function object with the correct return type' do
-      expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-      tags = object.docstring.tags(:return)
-      expect(tags.size).to eq(1)
-      expect(tags[0].tag_name).to eq('return')
-      expect(tags[0].text).to eq('')
-      expect(tags[0].types).to eq(['String'])
-    end
-  end
-
-  describe 'parsing a function with a non-conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do
-    let(:source) { <<-SOURCE
-# A simple foo function
-# @return [String] Hi there
-function foo() >> String {
-  notice 'hi there'
-}
-SOURCE
-    }
-
-    it 'should not output a warning if return types match' do
-      expect{ subject }.not_to output(/Documented return type does not match return type in function definition/).to_stdout_from_any_process
-    end
-  end
-
-  describe 'parsing a function with a conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-# @return [Integer] this is a lie.
-function foo() >> Struct[{'a' => Integer[1, 10]}] {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should prefer the return type from the function definition' do
-      expect{ subject }.to output(/\[warn\]: Documented return type does not match return type in function definition near \(stdin\):3\./).to_stdout_from_any_process
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-      tags = object.docstring.tags(:return)
-      expect(tags.size).to eq(1)
-      expect(tags[0].tag_name).to eq('return')
-      expect(tags[0].text).to eq('this is a lie.')
-      expect(tags[0].types).to eq(["Struct[{'a' => Integer[1, 10]}]"])
-    end
-  end
-
-  describe 'parsing a function without a return tag or return type in the function definition' do
-    let(:source) { <<-SOURCE
-# A simple foo function.
-function foo() {
-  notice 'hello world'
-}
-SOURCE
-    }
-
-    it 'should add a return tag with a default type value of Any' do
-      expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process
-      expect(subject.size).to eq(1)
-      object = subject.first
-      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
-      tags = object.docstring.tags(:return)
-      expect(tags.size).to eq(1)
-      expect(tags[0].tag_name).to eq('return')
-      expect(tags[0].text).to eq('')
-      expect(tags[0].types).to eq(['Any'])
-    end
-  end
-
-  describe 'parsing a function with a summary' do
-    context 'when the summary has fewer than 140 characters' do
-      let(:source) { <<-SOURCE
-# A simple foo function.
-# @summary A short summary.
-# @return [String] foo
-function foo() {
-  notice 'hello world'
-}
-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
-# A simple foo 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!!
-function foo() {
-  notice 'hello world'
-}
-
-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

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

@@ -1,729 +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 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