diff --git a/.rubocop.yml b/.rubocop.yml index 85aac0a87..fec26fe29 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -124,7 +124,7 @@ Layout/ArgumentAlignment: Layout/BeginEndAlignment: Enabled: false Layout/ClosingHeredocIndentation: - Enabled: false + Enabled: true Layout/EmptyComment: Enabled: false Layout/EmptyLineAfterGuardClause: @@ -140,7 +140,7 @@ Layout/FirstArgumentIndentation: Layout/HashAlignment: Enabled: false Layout/HeredocIndentation: - Enabled: false + Enabled: true Layout/LeadingEmptyLines: Enabled: false Layout/SpaceAroundMethodCallOperator: diff --git a/spec/acceptance/generate_markdown_spec.rb b/spec/acceptance/generate_markdown_spec.rb index d7a257864..925d0c92c 100644 --- a/spec/acceptance/generate_markdown_spec.rb +++ b/spec/acceptance/generate_markdown_spec.rb @@ -11,30 +11,30 @@ sut_tmp_path end - expected = <<-EOF -# Reference + expected = <<~'EOF' + # Reference -## Classes -* [`test`](#test): This class exists to serve as fixture data for testing the puppet strings face + ## Classes + * [`test`](#test): This class exists to serve as fixture data for testing the puppet strings face -## Classes + ## Classes -### test + ### test -#### Examples -```puppet -class { "test": } -``` + #### Examples + ```puppet + class { "test": } + ``` -#### Parameters + #### Parameters -##### `package_name` + ##### `package_name` -The name of the package + The name of the package -##### `service_name` + ##### `service_name` -The name of the service + The name of the service EOF diff --git a/spec/fixtures/acceptance/modules/test/lib/puppet/datatypes/acceptancedatatype.rb b/spec/fixtures/acceptance/modules/test/lib/puppet/datatypes/acceptancedatatype.rb index 6702fd059..f5195c440 100644 --- a/spec/fixtures/acceptance/modules/test/lib/puppet/datatypes/acceptancedatatype.rb +++ b/spec/fixtures/acceptance/modules/test/lib/puppet/datatypes/acceptancedatatype.rb @@ -10,7 +10,7 @@ # @param [Integer] param2 param2 func1 documentation # @return [Optional[String]] Puppet::DataTypes.create_type('AcceptanceDataType') do - interface <<-PUPPET + interface <<~'PUPPET' attributes => { param1 => Variant[Numeric, String[1,2]], param2 => { type => Optional[String[1]], value => "param2" } @@ -18,5 +18,5 @@ functions => { func1 => Callable[[String, Integer], Optional[String]] } - PUPPET + PUPPET end diff --git a/spec/fixtures/ruby/data_type.rb b/spec/fixtures/ruby/data_type.rb index 66b1bf52d..32382768f 100644 --- a/spec/fixtures/ruby/data_type.rb +++ b/spec/fixtures/ruby/data_type.rb @@ -8,7 +8,7 @@ # @param [Integer] param2 param2 documentation # @return [Optional[String]] Puppet::DataTypes.create_type('UnitDataType') do - interface <<-PUPPET + interface <<~'PUPPET' attributes => { param1 => Variant[Numeric, String[1,2]], param2 => { type => Optional[String[1]], value => "param2" } @@ -16,5 +16,5 @@ functions => { func1 => Callable[[String, Integer], Optional[String]] } - PUPPET + PUPPET end diff --git a/spec/fixtures/ruby/func3x.rb b/spec/fixtures/ruby/func3x.rb index e278ca0d1..3cb35e9af 100644 --- a/spec/fixtures/ruby/func3x.rb +++ b/spec/fixtures/ruby/func3x.rb @@ -1,12 +1,11 @@ # An example 3.x function -Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC - Documentation for an example 3.x function. - @param param1 [String] The first parameter. - @param param2 [Integer] The second parameter. - @return [Undef] - @example Calling the function. - func3x('hi', 10) - DOC - ) do |*args| - #... +Puppet::Parser::Functions.newfunction(:func3x, doc: <<~'DOC') do |*args| + Documentation for an example 3.x function. + @param param1 [String] The first parameter. + @param param2 [Integer] The second parameter. + @return [Undef] + @example Calling the function. + func3x('hi', 10) + DOC + # ... end diff --git a/spec/fixtures/ruby/resource_api.rb b/spec/fixtures/ruby/resource_api.rb index 13de6771f..1e30a5732 100644 --- a/spec/fixtures/ruby/resource_api.rb +++ b/spec/fixtures/ruby/resource_api.rb @@ -1,19 +1,19 @@ Puppet::ResourceApi.register_type( name: 'apt_key', - docs: <<-EOS, -@summary Example resource type using the new API. -@raise SomeError -This type provides Puppet with the capabilities to manage GPG keys needed -by apt to perform package validation. Apt has it's own GPG keyring that can -be manipulated through the `apt-key` command. -@example here's an example - apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': - source => 'http://apt.puppetlabs.com/pubkey.gpg' - } + docs: <<~'EOS', + @summary Example resource type using the new API. + @raise SomeError + This type provides Puppet with the capabilities to manage GPG keys needed + by apt to perform package validation. Apt has it's own GPG keyring that can + be manipulated through the `apt-key` command. + @example here's an example + apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': + source => 'http://apt.puppetlabs.com/pubkey.gpg' + } -**Autorequires**: -If Puppet is given the location of a key file which looks like an absolute -path this type will autorequire that file. + **Autorequires**: + If Puppet is given the location of a key file which looks like an absolute + path this type will autorequire that file. EOS attributes: { ensure: { diff --git a/spec/fixtures/ruby/resource_type.rb b/spec/fixtures/ruby/resource_type.rb index 557787c95..0c598ac3c 100644 --- a/spec/fixtures/ruby/resource_type.rb +++ b/spec/fixtures/ruby/resource_type.rb @@ -1,15 +1,15 @@ Puppet::Type.newtype(:database) do - desc <<-DESC -An example database server type. -@option opts :foo bar -@enum ensure :up Upstate -@enum ensure :down Downstate -@raise SomeError -@example here's an example - database { 'foo': - address => 'qux.baz.bar', - } -DESC + desc <<~'DESC' + An example database server type. + @option opts :foo bar + @enum ensure :up Upstate + @enum ensure :down Downstate + @raise SomeError + @example here's an example + database { 'foo': + address => 'qux.baz.bar', + } + DESC feature :encryption, 'The provider supports encryption.', methods: [:encrypt] ensurable do desc 'What state the database should be in.' diff --git a/spec/unit/puppet-strings/describe_spec.rb b/spec/unit/puppet-strings/describe_spec.rb index 100d8fe1f..d4543b0b2 100644 --- a/spec/unit/puppet-strings/describe_spec.rb +++ b/spec/unit/puppet-strings/describe_spec.rb @@ -15,125 +15,125 @@ before :each do # Populate the YARD registry with both Puppet and Ruby source - YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby) -Puppet::Type.newtype(:database) do - desc 'An example database server resource type.' -end + YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby) + Puppet::Type.newtype(:database) do + desc 'An example database server resource type.' + end SOURCE - YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby) -Puppet::ResourceApi.register_type( - name: 'apt_key', - docs: <<-EOS, -@summary Example resource type using the new API. -@raise SomeError -This type provides Puppet with the capabilities to manage GPG keys needed -by apt to perform package validation. Apt has it's own GPG keyring that can -be manipulated through the `apt-key` command. -@example here's an example - apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': - source => 'http://apt.puppetlabs.com/pubkey.gpg' - } - -**Autorequires**: -If Puppet is given the location of a key file which looks like an absolute -path this type will autorequire that file. - EOS -) + YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby) + Puppet::ResourceApi.register_type( + name: 'apt_key', + docs: <<~'EOS', + @summary Example resource type using the new API. + @raise SomeError + This type provides Puppet with the capabilities to manage GPG keys needed + by apt to perform package validation. Apt has it's own GPG keyring that can + be manipulated through the `apt-key` command. + @example here's an example + apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': + source => 'http://apt.puppetlabs.com/pubkey.gpg' + } + + **Autorequires**: + If Puppet is given the location of a key file which looks like an absolute + path this type will autorequire that file. + EOS + ) SOURCE - YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby) - Puppet::Type.type(:file).newproperty(:content) do - include Puppet::Util::Checksums - include Puppet::DataSync + YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby) + Puppet::Type.type(:file).newproperty(:content) do + include Puppet::Util::Checksums + include Puppet::DataSync - attr_reader :actual_content + attr_reader :actual_content - desc <<-'EOT' - The desired contents of a file, as a string. This attribute is mutually - exclusive with `source` and `target`. - EOT - end + desc <<~'EOT' + The desired contents of a file, as a string. This attribute is mutually + exclusive with `source` and `target`. + EOT + end SOURCE - YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby) - Puppet::Type.newtype(:file) do - include Puppet::Util::Checksums - include Puppet::Util::Backups - include Puppet::Util::SymbolicFileMode + YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby) + Puppet::Type.newtype(:file) do + include Puppet::Util::Checksums + include Puppet::Util::Backups + include Puppet::Util::SymbolicFileMode - @doc = "Manages files, including their content, ownership, and permissions. + @doc = "Manages files, including their content, ownership, and permissions. - The `file` type can manage normal files, directories, and symlinks; the - type should be specified in the `ensure` attribute." + The `file` type can manage normal files, directories, and symlinks; the + type should be specified in the `ensure` attribute." - newparam(:path) do - desc <<-'EOT' - The path to the file to manage. Must be fully qualified. + newparam(:path) do + desc <<~'EOT' + The path to the file to manage. Must be fully qualified. - On Windows, the path should include the drive letter and should use `/` as - the separator character (rather than `\\`). - EOT - isnamevar - end + On Windows, the path should include the drive letter and should use `/` as + the separator character (rather than `\`). + EOT + isnamevar + end - end + end SOURCE - YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby) -Puppet::Type.type(:file).newproperty(:source) do - include Puppet::Util::Checksums - include Puppet::DataSync + YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby) + Puppet::Type.type(:file).newproperty(:source) do + include Puppet::Util::Checksums + include Puppet::DataSync - attr_reader :actual_content + attr_reader :actual_content - desc <<-'EOT' - The desired contents of a file, as a string. This attribute is mutually - exclusive with `source` and `target`. - EOT -end + desc <<-'EOT' + The desired contents of a file, as a string. This attribute is mutually + exclusive with `source` and `target`. + EOT + end SOURCE end describe 'rendering DESCRIBE to stdout' do it 'outputs the expected describe content for the list of types' do - output = <<-DATA -These are the types known to puppet: -apt_key - This type provides Puppet with the capabiliti ... -database - An example database server resource type. -file - Manages files, including their content, owner ... + output = <<~'DATA' + These are the types known to puppet: + apt_key - This type provides Puppet with the capabiliti ... + database - An example database server resource type. + file - Manages files, including their content, owner ... DATA expect { described_class.render(nil, true) }.to output(output).to_stdout end it 'outputs the expected describe content for a type' do - output = <<-DATA + output = <<~'DATA' -file -==== -Manages files, including their content, ownership, and permissions. + file + ==== + Manages files, including their content, ownership, and permissions. -The `file` type can manage normal files, directories, and symlinks; the -type should be specified in the `ensure` attribute. + The `file` type can manage normal files, directories, and symlinks; the + type should be specified in the `ensure` attribute. -Parameters ----------- + Parameters + ---------- -- **content** -The desired contents of a file, as a string. This attribute is mutually -exclusive with `source` and `target`. + - **content** + The desired contents of a file, as a string. This attribute is mutually + exclusive with `source` and `target`. -- **path** -The path to the file to manage. Must be fully qualified. + - **path** + The path to the file to manage. Must be fully qualified. -On Windows, the path should include the drive letter and should use `/` as -the separator character (rather than `\\`). + On Windows, the path should include the drive letter and should use `/` as + the separator character (rather than `\`). -- **source** -The desired contents of a file, as a string. This attribute is mutually -exclusive with `source` and `target`. + - **source** + The desired contents of a file, as a string. This attribute is mutually + exclusive with `source` and `target`. -Providers ---------- + Providers + --------- DATA expect { described_class.render(['file']) }.to output(output).to_stdout end diff --git a/spec/unit/puppet-strings/json_spec.rb b/spec/unit/puppet-strings/json_spec.rb index 6b2e2a36f..d7ea83c29 100644 --- a/spec/unit/puppet-strings/json_spec.rb +++ b/spec/unit/puppet-strings/json_spec.rb @@ -7,222 +7,221 @@ describe PuppetStrings::Json do before :each do # Populate the YARD registry with both Puppet and Ruby source - expect(YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet).enumerator.length).to eq(2) -# A simple class. -# @todo Do a thing -# @note Some note -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { -} - -# A simple defined type. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -define dt(Integer $param1, $param2, String $param3 = hi) { -} + expect(YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :puppet).enumerator.length).to eq(2) + # A simple class. + # @todo Do a thing + # @note Some note + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + } + + # A simple defined type. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + define dt(Integer $param1, $param2, String $param3 = hi) { + } SOURCE - expect(YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet).enumerator.length).to eq(1) if TEST_PUPPET_PLANS -# A simple plan. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -plan plann(String $param1, $param2, Integer $param3 = 1) { -} + expect(YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :puppet).enumerator.length).to eq(1) if TEST_PUPPET_PLANS + # A simple plan. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + plan plann(String $param1, $param2, Integer $param3 = 1) { + } SOURCE # Only include Puppet functions for 4.1+ - expect(YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet).enumerator.length).to eq(1) if TEST_PUPPET_FUNCTIONS -# A simple function. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -# @return [Undef] Returns nothing. -function func(Integer $param1, $param2, String $param3 = hi) { -} + expect(YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :puppet).enumerator.length).to eq(1) if TEST_PUPPET_FUNCTIONS + # A simple function. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + # @return [Undef] Returns nothing. + function func(Integer $param1, $param2, String $param3 = hi) { + } SOURCE # Only include Puppet types for 5.0+ - expect(YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby).enumerator.length).to eq(1) if TEST_PUPPET_DATATYPES -# Basic Puppet Data Type in Ruby -# -# @param msg A message parameter -# @!method func1(param1, param2) -# func1 documentation -# @param [String] param1 param1 documentation -# @param [Integer] param2 param2 documentation -# @return [Optional[String]] -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - attributes => { - msg => String[1] - }, - functions => { - func1 => Callable[[String, Integer], Optional[String]] - } - PUPPET -end -SOURCE - - expect(YARD::Parser::SourceParser.parse_string(<<-SOURCE, :json).enumerator.length).to eq(1) -{ - "description": "Allows you to backup your database to local file.", - "input_method": "stdin", - "parameters": { - "database": { - "description": "Database to connect to", - "type": "Optional[String[1]]" - }, - "user": { - "description": "The user", - "type": "Optional[String[1]]" - }, - "password": { - "description": "The password", - "type": "Optional[String[1]]" - }, - "sql": { - "description": "Path to file you want backup to", - "type": "String[1]" - } - } -} + expect(YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby).enumerator.length).to eq(1) if TEST_PUPPET_DATATYPES + # Basic Puppet Data Type in Ruby + # + # @param msg A message parameter + # @!method func1(param1, param2) + # func1 documentation + # @param [String] param1 param1 documentation + # @param [Integer] param2 param2 documentation + # @return [Optional[String]] + Puppet::DataTypes.create_type('RubyDataType') do + interface <<~'PUPPET' + attributes => { + msg => String[1] + }, + functions => { + func1 => Callable[[String, Integer], Optional[String]] + } + PUPPET + end SOURCE - expect(YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby).enumerator.length).to eq(6) -Puppet::Parser::Functions.newfunction(:func3x, 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 - -# An example 4.x function. -Puppet::Functions.create_function(:func4x) do - # The first overload. - # @param param1 The first parameter. - # @param param2 The second parameter. - # @param param3 The third parameter. - # @return Returns nothing. - dispatch :foo do - param 'Integer', :param1 - param 'Any', :param2 - optional_param 'Array[String]', :param3 - return_type 'Undef' - end - - # @param param The first parameter. - # @param block The block parameter. - # @return Returns a string. - dispatch :other do - param 'Boolean', :param - block_param - return_type 'String' - end -end - -# An example 4.x function with only one signature. -Puppet::Functions.create_function(:func4x_1) do - # @param param1 The first parameter. - # @return [Undef] Returns nothing. - dispatch :foobarbaz do - param 'Integer', :param1 - end -end - -Puppet::Type.type(:database).provide :linux do - desc 'An example provider on Linux.' - confine kernel: 'Linux' - confine osfamily: 'RedHat' - defaultfor :kernel => 'Linux' - defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7' - has_feature :implements_some_feature - has_feature :some_other_feature - commands foo: '/usr/bin/foo' -end - -Puppet::Type.newtype(:database) do - desc 'An example database server resource type.' - feature :encryption, 'The provider supports encryption.', methods: [:encrypt] - ensurable do - desc 'What state the database should be in.' - defaultvalues - aliasvalue(:up, :present) - aliasvalue(:down, :absent) - defaultto :up - end + expect(YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :json).enumerator.length).to eq(1) + { + "description": "Allows you to backup your database to local file.", + "input_method": "stdin", + "parameters": { + "database": { + "description": "Database to connect to", + "type": "Optional[String[1]]" + }, + "user": { + "description": "The user", + "type": "Optional[String[1]]" + }, + "password": { + "description": "The password", + "type": "Optional[String[1]]" + }, + "sql": { + "description": "Path to file you want backup to", + "type": "String[1]" + } + } + } + SOURCE - newparam(:address) do - isnamevar - desc 'The database server name.' - end + expect(YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :ruby).enumerator.length).to eq(6) + Puppet::Parser::Functions.newfunction(:func3x, doc: <<~'DOC') do |*args| + An example 3.x function. + @param [String] first The first parameter. + @param second The second parameter. + @return [Undef] Returns nothing. + DOC + end - newparam(:encryption_key, required_features: :encryption) do - desc 'The encryption key to use.' - end + # An example 4.x function. + Puppet::Functions.create_function(:func4x) do + # The first overload. + # @param param1 The first parameter. + # @param param2 The second parameter. + # @param param3 The third parameter. + # @return Returns nothing. + dispatch :foo do + param 'Integer', :param1 + param 'Any', :param2 + optional_param 'Array[String]', :param3 + return_type 'Undef' + end + + # @param param The first parameter. + # @param block The block parameter. + # @return Returns a string. + dispatch :other do + param 'Boolean', :param + block_param + return_type 'String' + end + end - newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do - desc 'Whether or not to encrypt the database.' - defaultto false - end + # An example 4.x function with only one signature. + Puppet::Functions.create_function(:func4x_1) do + # @param param1 The first parameter. + # @return [Undef] Returns nothing. + dispatch :foobarbaz do + param 'Integer', :param1 + end + end - newproperty(:file) do - desc 'The database file to use.' - end + Puppet::Type.type(:database).provide :linux do + desc 'An example provider on Linux.' + confine kernel: 'Linux' + confine osfamily: 'RedHat' + defaultfor :kernel => 'Linux' + defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7' + has_feature :implements_some_feature + has_feature :some_other_feature + commands foo: '/usr/bin/foo' + end - newproperty(:log_level) do - desc 'The log level to use.' - newvalue(:debug) - newvalue(:warn) - newvalue(:error) - defaultto 'warn' - end -end + Puppet::Type.newtype(:database) do + desc 'An example database server resource type.' + feature :encryption, 'The provider supports encryption.', methods: [:encrypt] + ensurable do + desc 'What state the database should be in.' + defaultvalues + aliasvalue(:up, :present) + aliasvalue(:down, :absent) + defaultto :up + end + + newparam(:address) do + isnamevar + desc 'The database server name.' + end + + newparam(:encryption_key, required_features: :encryption) do + desc 'The encryption key to use.' + end + + newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do + desc 'Whether or not to encrypt the database.' + defaultto false + end + + newproperty(:file) do + desc 'The database file to use.' + end + + newproperty(:log_level) do + desc 'The log level to use.' + newvalue(:debug) + newvalue(:warn) + newvalue(:error) + defaultto 'warn' + end + end -Puppet::ResourceApi.register_type( - name: 'apt_key', - docs: <<-EOS, -@summary Example resource type using the new API. -@raise SomeError -This type provides Puppet with the capabilities to manage GPG keys needed -by apt to perform package validation. Apt has it's own GPG keyring that can -be manipulated through the `apt-key` command. -@example here's an example - apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': - source => 'http://apt.puppetlabs.com/pubkey.gpg' - } - -**Autorequires**: -If Puppet is given the location of a key file which looks like an absolute -path this type will autorequire that file. - EOS - attributes: { - ensure: { - type: 'Enum[present, absent]', - desc: 'Whether this apt key should be present or absent on the target system.' - }, - id: { - type: 'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]', - behaviour: :namevar, - desc: 'The ID of the key you want to manage.', - }, - # ... - created: { - type: 'String', - behaviour: :read_only, - desc: 'Date the key was created, in ISO format.', - }, - }, - autorequires: { - file: '$source', # will evaluate to the value of the `source` attribute - package: 'apt', - }, -) + Puppet::ResourceApi.register_type( + name: 'apt_key', + docs: <<~'EOS', + @summary Example resource type using the new API. + @raise SomeError + This type provides Puppet with the capabilities to manage GPG keys needed + by apt to perform package validation. Apt has it's own GPG keyring that can + be manipulated through the `apt-key` command. + @example here's an example + apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F': + source => 'http://apt.puppetlabs.com/pubkey.gpg' + } + + **Autorequires**: + If Puppet is given the location of a key file which looks like an absolute + path this type will autorequire that file. + EOS + attributes: { + ensure: { + type: 'Enum[present, absent]', + desc: 'Whether this apt key should be present or absent on the target system.' + }, + id: { + type: 'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]', + behaviour: :namevar, + desc: 'The ID of the key you want to manage.', + }, + # ... + created: { + type: 'String', + behaviour: :read_only, + desc: 'Date the key was created, in ISO format.', + }, + }, + autorequires: { + file: '$source', # will evaluate to the value of the `source` attribute + package: 'apt', + }, + ) SOURCE end diff --git a/spec/unit/puppet-strings/markdown/base_spec.rb b/spec/unit/puppet-strings/markdown/base_spec.rb index 710cc26ca..8f35f2252 100644 --- a/spec/unit/puppet-strings/markdown/base_spec.rb +++ b/spec/unit/puppet-strings/markdown/base_spec.rb @@ -5,15 +5,15 @@ describe PuppetStrings::Markdown::Base do context 'basic class' do before :each do - YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) -# An overview -# @api private -# @summary A simple class. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { -} + YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :puppet) + # An overview + # @api private + # @summary A simple class. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + } SOURCE end @@ -69,24 +69,24 @@ class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { end context 'less basic class' do before :each do - YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet) -# An overview -# It's a longer overview -# Ya know? -# @example A simple example. -# class { 'klass::yeah': -# param1 => 1, -# } -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -class klass::yeah( - Integer $param1, - $param2, - String $param3 = hi -) inherits foo::bar { - -} + YARD::Parser::SourceParser.parse_string(<<~'SOURCE', :puppet) + # An overview + # It's a longer overview + # Ya know? + # @example A simple example. + # class { 'klass::yeah': + # param1 => 1, + # } + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + class klass::yeah( + Integer $param1, + $param2, + String $param3 = hi + ) inherits foo::bar { + + } SOURCE end diff --git a/spec/unit/puppet-strings/yard/code_objects/task_spec.rb b/spec/unit/puppet-strings/yard/code_objects/task_spec.rb index 42857702d..f0edd015f 100644 --- a/spec/unit/puppet-strings/yard/code_objects/task_spec.rb +++ b/spec/unit/puppet-strings/yard/code_objects/task_spec.rb @@ -7,32 +7,30 @@ describe PuppetStrings::Yard::CodeObjects::Task do subject(:spec_subject) { described_class.new(statement) } - let(:source) do - <<-SOURCE -{ - "description": "Allows you to backup your database to local file.", - "input_method": "stdin", - "parameters": { - "database": { - "description": "Database to connect to", - "type": "Optional[String[1]]" - }, - "user": { - "description": "The user", - "type": "Optional[String[1]]" - }, - "password": { - "description": "The password", - "type": "Optional[String[1]]" - }, - "sql": { - "description": "Path to file you want backup to", - "type": "String[1]" + let(:source) { <<~'SOURCE' } + { + "description": "Allows you to backup your database to local file.", + "input_method": "stdin", + "parameters": { + "database": { + "description": "Database to connect to", + "type": "Optional[String[1]]" + }, + "user": { + "description": "The user", + "type": "Optional[String[1]]" + }, + "password": { + "description": "The password", + "type": "Optional[String[1]]" + }, + "sql": { + "description": "Path to file you want backup to", + "type": "String[1]" + } + } } - } -} SOURCE - end let(:json) { JSON.parse(source) } let(:statement) { PuppetStrings::Yard::Parsers::JSON::TaskStatement.new(json, source, 'test.json') } diff --git a/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb index 60609ae18..650b7323e 100644 --- a/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb @@ -10,19 +10,17 @@ end describe 'parsing task metadata with a syntax error' do - let(:source) do - <<-SOURCE -{ - "input_method": "stdin", - "parameters": - "database": { - "description": "Database to connect to", - "type": "Optional[String[1]]" - } - } -} + let(:source) { <<~'SOURCE' } + { + "input_method": "stdin", + "parameters": + "database": { + "description": "Database to connect to", + "type": "Optional[String[1]]" + } + } + } SOURCE - end it 'logs an error' do expect { spec_subject }.to output(%r{\[error\]: Failed to parse \(stdin\):}).to_stdout_from_any_process @@ -31,31 +29,29 @@ end describe 'parsing task metadata with a missing description' do - let(:source) do - <<-SOURCE -{ - "input_method": "stdin", - "parameters": { - "database": { - "description": "Database to connect to", - "type": "Optional[String[1]]" - }, - "user": { - "description": "The user", - "type": "Optional[String[1]]" - }, - "password": { - "description": "The password", - "type": "Optional[String[1]]" - }, - "sql": { - "description": "Path to file you want backup to", - "type": "String[1]" - } - } -} + let(:source) { <<~'SOURCE' } + { + "input_method": "stdin", + "parameters": { + "database": { + "description": "Database to connect to", + "type": "Optional[String[1]]" + }, + "user": { + "description": "The user", + "type": "Optional[String[1]]" + }, + "password": { + "description": "The password", + "type": "Optional[String[1]]" + }, + "sql": { + "description": "Path to file you want backup to", + "type": "String[1]" + } + } + } SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing a description for Puppet Task \(stdin\)}).to_stdout_from_any_process @@ -63,33 +59,31 @@ end describe 'parsing task metadata with a description' do - let(:source) do - <<-SOURCE -{ - "description": "Allows you to backup your database to local file.", - "input_method": "stdin", - "parameters": { - "database": { - "description": "Database to connect to", - "type": "Optional[String[1]]" - }, - "user": { - "description": "The user", - "type": "Optional[String[1]]" - }, - "password": { - "description": "The password", - "type": "Optional[String[1]]" - }, - "sql": { - "description": "Path to file you want backup to", - "type": "String[1]" - } - } -} + let(:source) { <<~'SOURCE' } + { + "description": "Allows you to backup your database to local file.", + "input_method": "stdin", + "parameters": { + "database": { + "description": "Database to connect to", + "type": "Optional[String[1]]" + }, + "user": { + "description": "The user", + "type": "Optional[String[1]]" + }, + "password": { + "description": "The password", + "type": "Optional[String[1]]" + }, + "sql": { + "description": "Path to file you want backup to", + "type": "String[1]" + } + } + } SOURCE - end it 'registers a task object' do expect(spec_subject.size).to eq(1) @@ -100,19 +94,17 @@ end describe 'parsing task metadata with a missing parameter description' do - let(:source) do - <<-SOURCE -{ - "description": "Allows you to backup your database to local file.", - "input_method": "stdin", - "parameters": { - "database": { - "type": "Optional[String[1]]" - } - } -} + let(:source) { <<~'SOURCE' } + { + "description": "Allows you to backup your database to local file.", + "input_method": "stdin", + "parameters": { + "database": { + "type": "Optional[String[1]]" + } + } + } SOURCE - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing description for param 'database' in Puppet Task \(stdin\)}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb index 3f919f6ce..9fedb2fd2 100644 --- a/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb @@ -35,19 +35,17 @@ end describe 'parsing a class with a docstring' do - let(:source) do - <<-SOURCE -# A simple foo class. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'registers a class object' do expect(spec_subject.size).to eq(1) @@ -77,20 +75,18 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { end describe 'parsing a class with a missing parameter' do - let(:source) do - <<-SOURCE -# A simple foo class. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -# @param param4 missing! -class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + # @param param4 missing! + class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):6\.}).to_stdout_from_any_process @@ -98,18 +94,16 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { end describe 'parsing a class with a missing @param tag' do - let(:source) do - <<-SOURCE -# A simple foo class. -# @param param1 First param. -# @param param2 Second param. -class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @param param1 First param. + # @param param2 Second param. + class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):4\.}).to_stdout_from_any_process @@ -117,19 +111,17 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { end describe 'parsing a class with a typed parameter that also has a @param tag type which matches' do - let(:source) do - <<-SOURCE -# A simple foo class. -# @param [Integer] param1 First param. -# @param param2 Second param. -# @param param3 Third param. -class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @param [Integer] param1 First param. + # @param param2 Second param. + # @param param3 Third param. + class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'respects the type that was documented' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -141,19 +133,17 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { end describe 'parsing a class with a typed parameter that also has a @param tag type which does not match' do - let(:source) do - <<-SOURCE -# A simple foo class. -# @param [Boolean] param1 First param. -# @param param2 Second param. -# @param param3 Third param. -class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @param [Boolean] param1 First param. + # @param param2 Second param. + # @param param3 Third param. + class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'outputs a warning' do expect { spec_subject } @@ -165,19 +155,17 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { end describe 'parsing a class with a untyped parameter that also has a @param tag type' do - let(:source) do - <<-SOURCE -# A simple foo class. -# @param param1 First param. -# @param [Boolean] param2 Second param. -# @param param3 Third param. -class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @param param1 First param. + # @param [Boolean] param2 Second param. + # @param param3 Third param. + class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'respects the type that was documented' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -190,17 +178,15 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { describe 'parsing a class with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE - # A simple foo class. - # @summary A short summary. - class foo() { - file { '/tmp/foo': - ensure => present - } - } + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @summary A short summary. + class foo() { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -211,17 +197,15 @@ class foo() { end context 'when the summary has more than 140 characters' do - let(:source) do - <<-SOURCE - # A simple foo class. - # @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!! - class foo() { - file { '/tmp/foo': - ensure => present - } - } + let(:source) { <<~'SOURCE' } + # A simple foo class. + # @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!! + class foo() { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_class 'foo' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb index fd7e57372..c40939ad3 100644 --- a/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb @@ -36,13 +36,11 @@ describe 'parsing a data type alias with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE - # A simple foo type. - # @summary A short summary. - type Testype = String[1] - SOURCE - end + let(:source) { <<~'SOURCE' } + # A simple foo type. + # @summary A short summary. + type Testype = String[1] + SOURCE it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -53,13 +51,11 @@ end context 'when the summary has more than 140 characters' do - let(:source) do - <<-SOURCE - # A simple foo type. - # @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!! - type Testype = String[1] - SOURCE - end + let(:source) { <<~'SOURCE' } + # A simple foo type. + # @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!! + type Testype = String[1] + SOURCE it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_data_type_alias 'Testype' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb index c7ab7e218..5807d1790 100644 --- a/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb @@ -35,20 +35,18 @@ end describe 'parsing a defined type with a docstring' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @param name The type name. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @param name The type name. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'does not output a warning for title/name' do expect { spec_subject }.not_to output(%r{\[warn\].*(name|title).*}).to_stdout_from_any_process @@ -85,20 +83,18 @@ end describe 'parsing a defined type with a missing parameter' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @param param1 First param. -# @param param2 Second param. -# @param param3 Third param. -# @param param4 missing! -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + # @param param4 missing! + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The @param tag for parameter 'param4' has no matching parameter at \(stdin\):6\.}).to_stdout_from_any_process @@ -106,18 +102,16 @@ end describe 'parsing a defined type with a missing @param tag' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @param param1 First param. -# @param param2 Second param. -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @param param1 First param. + # @param param2 Second param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):4\.}).to_stdout_from_any_process @@ -125,19 +119,17 @@ end describe 'parsing a defined type with a typed parameter that also has a @param tag type which matches' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @param [Integer] param1 First param. -# @param param2 Second param. -# @param param3 Third param. -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @param [Integer] param1 First param. + # @param param2 Second param. + # @param param3 Third param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'respects the type that was documented' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -149,19 +141,17 @@ end describe 'parsing a defined type with a typed parameter that also has a @param tag type which does not match' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @param [Boolean] param1 First param. -# @param param2 Second param. -# @param param3 Third param. -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @param [Boolean] param1 First param. + # @param param2 Second param. + # @param param3 Third param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'outputs a warning' do expect { spec_subject } @@ -171,19 +161,17 @@ end describe 'parsing a defined type with a untyped parameter that also has a @param tag type' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @param param1 First param. -# @param [Boolean] param2 Second param. -# @param param3 Third param. -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @param param1 First param. + # @param [Boolean] param2 Second param. + # @param param3 Third param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'respects the type that was documented' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -196,20 +184,18 @@ describe 'parsing a defined type with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @summary A short summary. -# @param param1 First param. -# @param [Boolean] param2 Second param. -# @param param3 Third param. -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @summary A short summary. + # @param param1 First param. + # @param [Boolean] param2 Second param. + # @param param3 Third param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -220,20 +206,18 @@ end context 'when the summary has more than 140 characters' do - let(:source) do - <<-SOURCE -# A simple foo defined type. -# @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!! -# @param param1 First param. -# @param [Boolean] param2 Second param. -# @param param3 Third param. -define foo(Integer $param1, $param2, String $param3 = hi) { - file { '/tmp/foo': - ensure => present - } -} + let(:source) { <<~'SOURCE' } + # A simple foo defined type. + # @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!! + # @param param1 First param. + # @param [Boolean] param2 Second param. + # @param param3 Third param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_defined_type 'foo' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb index 0eeb1d1c9..aea363e8f 100644 --- a/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb @@ -36,19 +36,17 @@ end describe 'parsing a function with a docstring' do - let(:source) do - <<-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 -} + 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 - end it 'registers a function object' do expect(spec_subject.size).to eq(1) @@ -83,19 +81,17 @@ end describe 'parsing a function with a missing parameter' do - let(:source) do - <<-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' -} + 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 - end it 'outputs a warning' do expect { spec_subject } @@ -105,17 +101,15 @@ end describe 'parsing a function with a missing @param tag' do - let(:source) do - <<-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' -} + 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 - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @param tag for parameter 'param3' near \(stdin\):5\.}).to_stdout_from_any_process @@ -123,18 +117,16 @@ end describe 'parsing a function with a typed parameter that also has a @param tag type which matches' do - let(:source) do - <<-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' -} + 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 - end it 'respects the type that was documented' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -146,18 +138,16 @@ end describe 'parsing a function with a typed parameter that also has a @param tag type which does not match' do - let(:source) do - <<-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' -} + 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 - end it 'outputs a warning' do expect { spec_subject } @@ -169,18 +159,16 @@ end describe 'parsing a function with a untyped parameter that also has a @param tag type' do - let(:source) do - <<-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' -} + 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 - end it 'respects the type that was documented' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -192,17 +180,15 @@ end describe 'parsing a function with a missing @return tag' do - let(:source) do - <<-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' -} + 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 - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @return tag near \(stdin\):5\.}).to_stdout_from_any_process @@ -210,14 +196,12 @@ 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) do - <<-SOURCE -# A simple foo function. -function foo() >> String { - notice 'hello world' -} + let(:source) { <<~'SOURCE' } + # A simple foo function. + function foo() >> String { + notice 'hello world' + } SOURCE - end it 'registers a function object with the correct return type' do expect { spec_subject }.to output(%r{\[warn\]: Missing @return tag near \(stdin\):2\.}).to_stdout_from_any_process @@ -233,15 +217,13 @@ end describe 'parsing a function with a non-conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do - let(:source) do - <<-SOURCE -# A simple foo function -# @return [String] Hi there -function foo() >> String { - notice 'hi there' -} + let(:source) { <<~'SOURCE' } + # A simple foo function + # @return [String] Hi there + function foo() >> String { + notice 'hi there' + } SOURCE - end it 'does not output a warning if return types match' do expect { spec_subject }.not_to output(%r{Documented return type does not match return type in function definition}).to_stdout_from_any_process @@ -249,15 +231,13 @@ end describe 'parsing a function with a conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do - let(:source) do - <<-SOURCE -# A simple foo function. -# @return [Integer] this is a lie. -function foo() >> Struct[{'a' => Integer[1, 10]}] { - notice 'hello world' -} + let(:source) { <<~'SOURCE' } + # A simple foo function. + # @return [Integer] this is a lie. + function foo() >> Struct[{'a' => Integer[1, 10]}] { + notice 'hello world' + } SOURCE - end it 'prefers the return type from the function definition' do expect { spec_subject }.to output(%r{\[warn\]: Documented return type does not match return type in function definition near \(stdin\):3\.}).to_stdout_from_any_process @@ -273,15 +253,13 @@ end describe 'parsing a function with return tag without type', if: TEST_FUNCTION_RETURN_TYPE do - let(:source) do - <<-SOURCE -# A simple foo function. -# @return This is something. -function foo() >> Struct[{'a' => Integer[1, 10]}] { - notice 'hello world' -} + let(:source) { <<~'SOURCE' } + # A simple foo function. + # @return This is something. + function foo() >> Struct[{'a' => Integer[1, 10]}] { + notice 'hello world' + } SOURCE - end it 'gets the return type from the function definition' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -297,14 +275,12 @@ end describe 'parsing a function without a return tag or return type in the function definition' do - let(:source) do - <<-SOURCE -# A simple foo function. -function foo() { - notice 'hello world' -} + let(:source) { <<~'SOURCE' } + # A simple foo function. + function foo() { + notice 'hello world' + } SOURCE - end it 'adds a return tag with a default type value of Any' do expect { spec_subject }.to output(%r{\[warn\]: Missing @return tag near \(stdin\):2\.}).to_stdout_from_any_process @@ -321,16 +297,14 @@ describe 'parsing a function with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE -# A simple foo function. -# @summary A short summary. -# @return [String] foo -function foo() { - notice 'hello world' -} + let(:source) { <<~'SOURCE' } + # A simple foo function. + # @summary A short summary. + # @return [String] foo + function foo() { + notice 'hello world' + } SOURCE - end it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -341,16 +315,14 @@ end context 'when the summary has more than 140 characters' do - let(:source) do - <<-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' -} + 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 - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb index c2858fa7d..2d5fbe177 100644 --- a/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb @@ -31,12 +31,10 @@ def suppress_yard_logging end describe 'parsing an empty data type definition' do - let(:source) do - <<-SOURCE -Puppet::DataTypes.create_type('RubyDataType') do -end -SOURCE - end + let(:source) { <<~'SOURCE' } + Puppet::DataTypes.create_type('RubyDataType') do + end + SOURCE it 'registers a data type object with no param tags or functions' do expect(spec_subject.size).to eq(1) @@ -56,18 +54,16 @@ def suppress_yard_logging end describe 'parsing a data type definition with missing param tags' do - let(:source) do - <<-SOURCE -# An example Puppet Data Type in Ruby. -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - attributes => { - msg => String[1], - } - PUPPET -end -SOURCE - end + 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 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @param tag for attribute 'msg' near \(stdin\):2}).to_stdout_from_any_process @@ -102,18 +98,16 @@ def suppress_yard_logging describe 'parsing a data type definition with missing function' do context 'which has parameters' do - let(:source) do - <<-SOURCE -# An example Puppet Data Type in Ruby. -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - functions => { - func1 => Callable[[Integer, String], String] - } - PUPPET -end -SOURCE - end + let(:source) { <<~'SOURCE' } + # An example Puppet Data Type in Ruby. + Puppet::DataTypes.create_type('RubyDataType') do + interface <<~'PUPPET' + functions => { + func1 => Callable[[Integer, String], String] + } + PUPPET + end + SOURCE it 'outputs a warning about the missing functions' do expect { spec_subject }.to output(%r{\[warn\]: Missing @!method tag for function 'func1' near \(stdin\):2}m).to_stdout_from_any_process @@ -151,19 +145,17 @@ def suppress_yard_logging end context 'which has multiple functions' do - let(:source) do - <<-SOURCE -# An example Puppet Data Type in Ruby. -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - functions => { - func1 => Callable[[], String], - func2 => Callable[[Integer], String] - } - PUPPET -end -SOURCE - end + let(:source) { <<~'SOURCE' } + # An example Puppet Data Type in Ruby. + Puppet::DataTypes.create_type('RubyDataType') do + interface <<~'PUPPET' + functions => { + func1 => Callable[[], String], + func2 => Callable[[Integer], String] + } + PUPPET + end + SOURCE it 'outputs a warning about the first missing function' do expect { spec_subject }.to output(%r{\[warn\]: Missing @!method tag for function 'func1' near \(stdin\):2}m).to_stdout_from_any_process @@ -201,26 +193,24 @@ def suppress_yard_logging end describe 'parsing a data type definition with extra tags' do - let(:source) do - <<-SOURCE -# An example Puppet Data Type in Ruby. -# @param msg A message parameter. -# @param arg1 Optional String parameter. Defaults to 'param'. -# -# @!method does_not_exist -# -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - attributes => { - msg => Numeric, - }, - functions => { - func1 => Callable[[], Optional[String]] - } - PUPPET -end -SOURCE - end + let(:source) { <<~'SOURCE' } + # An example Puppet Data Type in Ruby. + # @param msg A message parameter. + # @param arg1 Optional String parameter. Defaults to 'param'. + # + # @!method does_not_exist + # + Puppet::DataTypes.create_type('RubyDataType') do + interface <<~'PUPPET' + attributes => { + msg => Numeric, + }, + functions => { + func1 => Callable[[], Optional[String]] + } + PUPPET + end + SOURCE it 'outputs a warning about the extra attribute' do expect { spec_subject }.to output(%r{\[warn\]: The @param tag for 'arg1' has no matching attribute near \(stdin\):7}m).to_stdout_from_any_process @@ -265,32 +255,30 @@ def suppress_yard_logging describe 'parsing a valid data type definition' do # TODO: What about testing for `type_parameters => {}` # e.g. https://github.com/puppetlabs/puppet/blob/main/lib/puppet/datatypes/error.rb - let(:source) do - <<-SOURCE -# An example Puppet Data Type in Ruby. -# -# @param msg A message parameter5. -# @param arg1 Optional String parameter5. Defaults to 'param'. -# -# @!method func1(foo, bar) -# func1 documentation -# @param [String] foo foo documentation -# @param [Integer] bar bar documentation -# @return [Optional[String]] -# -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - attributes => { - msg => Variant[Numeric, String[1,2]], - arg1 => { type => Optional[String[1]], value => "param" } - }, - functions => { - func1 => Callable[[String, Integer], Optional[String]] - } - PUPPET -end -SOURCE - end + let(:source) { <<~'SOURCE' } + # An example Puppet Data Type in Ruby. + # + # @param msg A message parameter5. + # @param arg1 Optional String parameter5. Defaults to 'param'. + # + # @!method func1(foo, bar) + # func1 documentation + # @param [String] foo foo documentation + # @param [Integer] bar bar documentation + # @return [Optional[String]] + # + Puppet::DataTypes.create_type('RubyDataType') do + interface <<~'PUPPET' + attributes => { + msg => Variant[Numeric, String[1,2]], + arg1 => { type => Optional[String[1]], value => "param" } + }, + functions => { + func1 => Callable[[String, Integer], Optional[String]] + } + PUPPET + end + SOURCE it 'registers a data type object' do expect(spec_subject.size).to eq(1) @@ -337,8 +325,7 @@ def suppress_yard_logging end context 'with multiple interfaces' do - let(:source) do - <<-SOURCE + let(:source) { <<~'SOURCE' } # An example Puppet Data Type in Ruby. # # @param msg A message parameter5. @@ -352,7 +339,7 @@ def suppress_yard_logging # Puppet::DataTypes.create_type('RubyDataType') do if 1 == 2 - interface <<-PUPPET + interface <<~'PUPPET' This interface is invalid because of this text! attributes => { msg1 => Variant[Numeric, String[1,2]], @@ -360,29 +347,28 @@ def suppress_yard_logging functions => { func1 => Callable[[String, Integer], Optional[String]] } - PUPPET + PUPPET elsif 1 == 3 - interface <<-PUPPET + interface <<~'PUPPET' attributes => { msg2 => Variant[Numeric, String[1,2]], }, functions => { func2 => Callable[[String, Integer], Optional[String]] } - PUPPET + PUPPET else - interface <<-PUPPET + interface <<~'PUPPET' attributes => { msg3 => Variant[Numeric, String[1,2]], }, functions => { func3 => Callable[[String, Integer], Optional[String]] } - PUPPET + PUPPET end end - SOURCE - end + SOURCE it 'registers only the first valid interface' do suppress_yard_logging @@ -403,33 +389,31 @@ def suppress_yard_logging end context 'with missing, partial and addition function parameters' do - let(:source) do - <<-SOURCE -# An example Puppet Data Type in Ruby. -# -# @!method func1(foo1, foo2) -# func1 docs -# @param [String] foo1 param1 documentation -# @param [Integer] missing docs should exist -# @param [String] extra Should not exist -# @return [Integer] This is wrong -# -# @!method func2(param1, param2) -# func2 docs - missing a parameter -# @param [String] param1 param1 documentation -# -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - attributes => { - }, - functions => { - func1 => Callable[[Integer, Integer], Optional[String]], - func2 => Callable[[Integer, Integer], Optional[String]] - } - PUPPET -end -SOURCE - end + let(:source) { <<~'SOURCE' } + # An example Puppet Data Type in Ruby. + # + # @!method func1(foo1, foo2) + # func1 docs + # @param [String] foo1 param1 documentation + # @param [Integer] missing docs should exist + # @param [String] extra Should not exist + # @return [Integer] This is wrong + # + # @!method func2(param1, param2) + # func2 docs - missing a parameter + # @param [String] param1 param1 documentation + # + Puppet::DataTypes.create_type('RubyDataType') do + interface <<~'PUPPET' + attributes => { + }, + functions => { + func1 => Callable[[Integer, Integer], Optional[String]], + func2 => Callable[[Integer, Integer], Optional[String]] + } + PUPPET + end + SOURCE it 'outputs a warning about the incorrect return type' do expect { spec_subject }.to output(%r{\[warn\]: The @return tag for 'func1' has a different type definition .+ Expected \["Optional\[String\]"\]}m).to_stdout_from_any_process @@ -499,19 +483,17 @@ def suppress_yard_logging { value: '0.31415e1', expected: 3.1415 }, ].each do |testcase| describe "parsing a valid data type definition with numeric default #{testcase[:value]}" do - let(:source) do - <<-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 - end + 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 'registers a data type object' do expect(spec_subject.size).to eq(1) @@ -524,25 +506,23 @@ def suppress_yard_logging end describe 'parsing an invalid data type definition' do - let(:source) do - <<-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" } - }, - functions => { - func1 => Callable[[], Integer] - } - PUPPET -end -SOURCE - end + 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" } + }, + functions => { + func1 => Callable[[], Integer] + } + PUPPET + end + SOURCE it 'registers a partial data type object' do suppress_yard_logging @@ -577,18 +557,16 @@ def suppress_yard_logging describe 'parsing a data type with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE -# An example Puppet Data Type in Ruby. -# -# @summary A short summary. -Puppet::DataTypes.create_type('RubyDataType') do - interface <<-PUPPET - attributes => { } - PUPPET -end -SOURCE - end + 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 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -599,18 +577,16 @@ def suppress_yard_logging end context 'when the summary has more than 140 characters' do - let(:source) do - <<-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 - end + 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 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_data_type 'RubyDataType' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb index 50f8889cf..08ee26987 100644 --- a/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb @@ -19,12 +19,10 @@ describe 'parsing 3.x API functions' do describe 'parsing a function with a missing docstring' do - let(:source) do - <<-SOURCE -Puppet::Parser::Functions.newfunction(:foo) do |*args| -end + let(:source) { <<~'SOURCE' } + Puppet::Parser::Functions.newfunction(:foo) do |*args| + end SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\.}).to_stdout_from_any_process @@ -32,18 +30,26 @@ end describe 'parsing a function with a doc parameter' do - let(:source) do - <<-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 + # Bug: Putting `) do |*args|` on the first line rather than right after + # the end of the heredoc block causes the docstring to be trimmed. This is + # probably related to https://github.com/lsegal/yard/issues/779. The code + # in PuppetStrings::Yard::Handlers::Ruby::Base has a special work around + # for this, but it seems to be limited by how much data YARD provides, and + # it often isn’t enough. + # + # Given that this occurs only in old-style functions, it’s probably not + # worth pursuing. + 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 - end it 'registers a function object' do expect(spec_subject.size).to eq(1) @@ -75,20 +81,28 @@ end describe 'parsing a function with a doc parameter which has a newline between the namespace and the newfunction call' do - let(:source) do - <<-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 + # Bug: Putting `) do |*args|` on the first line rather than right after + # the end of the heredoc block causes the docstring to be trimmed. This is + # probably related to https://github.com/lsegal/yard/issues/779. The code + # in PuppetStrings::Yard::Handlers::Ruby::Base has a special work around + # for this, but it seems to be limited by how much data YARD provides, and + # it often isn’t enough. + # + # Given that this occurs only in old-style functions, it’s probably not + # worth pursuing. + 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 - end it 'registers a function object' do expect(spec_subject.size).to eq(1) @@ -120,16 +134,15 @@ module Puppet::Parser::Functions end describe 'parsing a function with a missing @return tag' do - let(:source) do - <<-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 + 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 - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @return tag near \(stdin\):1}).to_stdout_from_any_process @@ -139,12 +152,10 @@ module Puppet::Parser::Functions describe 'parsing 4.x API functions' do describe 'parsing a function with a missing docstring' do - let(:source) do - <<-SOURCE -Puppet::Functions.create_function(:foo) do -end + let(:source) { <<~'SOURCE' } + Puppet::Functions.create_function(:foo) do + end SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing documentation for Puppet function 'foo' at \(stdin\):1\.}).to_stdout_from_any_process @@ -152,13 +163,11 @@ module Puppet::Parser::Functions end describe 'parsing a function with a simple docstring' do - let(:source) do - <<-SOURCE -# An example 4.x function. -Puppet::Functions.create_function(:foo) do -end + let(:source) { <<~'SOURCE' } + # An example 4.x function. + Puppet::Functions.create_function(:foo) do + end SOURCE - end it 'registers a function object' do expect(spec_subject.size).to eq(1) @@ -177,19 +186,17 @@ module Puppet::Parser::Functions end describe 'parsing a function without any dispatches' do - let(:source) do - <<-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 + 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 - end it 'registers a function object' do expect(spec_subject.size).to eq(1) @@ -224,25 +231,23 @@ def foo(param1, param2, param3 = nil) end describe 'parsing a function with a single dispatch' do - let(:source) do - <<-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 + 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 - end it 'registers a function object without any overload tags' do expect(spec_subject.size).to eq(1) @@ -278,26 +283,24 @@ def foo(param1, param2, param3 = nil) end describe 'parsing a function using only return_type' do - let(:source) do - <<-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 + 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 - end it 'does not throw an error with no @return' do expect { spec_subject }.not_to raise_error @@ -312,24 +315,22 @@ def foo(param1, param2, param3 = nil) end describe 'parsing a function with various dispatch parameters.' do - let(:source) do - <<-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 + 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 - end it 'registers a function object with the expected parameters' do expect(spec_subject.size).to eq(1) @@ -368,18 +369,16 @@ def foo(param1, param2, param3 = nil) end describe 'parsing a function with an optional repeated param.' do - let(:source) do - <<-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 + 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 - end it 'registers a function object with the expected parameters' do expect(spec_subject.size).to eq(1) @@ -409,18 +408,16 @@ def foo(param1, param2, param3 = nil) end describe 'parsing a function with a block param with one parameter' do - let(:source) do - <<-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 + 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 - end it 'registers a function object with the expected parameters' do expect(spec_subject.size).to eq(1) @@ -450,18 +447,16 @@ def foo(param1, param2, param3 = nil) end describe 'parsing a function with a block param with two parameter' do - let(:source) do - <<-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 + 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 - end it 'registers a function object with the expected parameters' do expect(spec_subject.size).to eq(1) @@ -492,39 +487,37 @@ def foo(param1, param2, param3 = nil) end describe 'parsing a function with a multiple dispatches' do - let(:source) do - <<-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 + 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 - end it 'registers a function object with overload tags' do expect(spec_subject.size).to eq(1) @@ -584,16 +577,14 @@ def other(b) end describe 'parsing a function with a namespaced name' do - let(:source) do - <<-SOURCE -# An example 4.x function. -Puppet::Functions.create_function(:'foo::bar::baz') do - # @return [Undef] - dispatch :foo do - end -end + let(:source) { <<~'SOURCE' } + # An example 4.x function. + Puppet::Functions.create_function(:'foo::bar::baz') do + # @return [Undef] + dispatch :foo do + end + end SOURCE - end it 'outputs the name correctly as a symbol' do expect(spec_subject.size).to eq(1) @@ -602,17 +593,15 @@ def other(b) end describe 'parsing a function with a missing parameter' do - let(:source) do - <<-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 + 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 - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The @param tag for parameter 'missing' has no matching parameter at \(stdin\):5}).to_stdout_from_any_process @@ -620,17 +609,15 @@ def other(b) end describe 'parsing a function with a missing @param tag' do - let(:source) do - <<-SOURCE -# An example 4.x function. -Puppet::Functions.create_function(:foo) do - # @return [Undef] Returns nothing. - dispatch :foo do - param 'String', :param1 - end -end + 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 - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @param tag for parameter 'param1' near \(stdin\):5}).to_stdout_from_any_process @@ -638,18 +625,16 @@ def other(b) end describe 'parsing a function with a typed @param tag' do - let(:source) do - <<-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 + 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 - end it 'outputs a warning' do expect { spec_subject } @@ -661,17 +646,15 @@ def other(b) end describe 'parsing a function with a typed @param tag' do - let(:source) do - <<-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 + 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 - end it 'outputs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing @return tag near \(stdin\):4}).to_stdout_from_any_process @@ -679,17 +662,15 @@ def other(b) end describe 'parsing a function with a root @param tag' do - let(:source) do - <<-SOURCE -# An example 4.x function. -# @param param Nope. -Puppet::Functions.create_function(:foo) do - # @return [Undef] - dispatch :foo do - end -end + 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 - end it 'outputs a warning' do expect { spec_subject } @@ -701,17 +682,15 @@ def other(b) end describe 'parsing a function with a root @overload tag' do - let(:source) do - <<-SOURCE -# An example 4.x function. -# @overload foo -Puppet::Functions.create_function(:foo) do - # @return [Undef] - dispatch :foo do - end -end + let(:source) { <<~'SOURCE' } + # An example 4.x function. + # @overload foo + Puppet::Functions.create_function(:foo) do + # @return [Undef] + dispatch :foo do + end + end SOURCE - end it 'outputs a warning' do expect { spec_subject } @@ -723,17 +702,15 @@ def other(b) end describe 'parsing a function with a root @return tag' do - let(:source) do - <<-SOURCE -# An example 4.x function. -# @return [Undef] foo -Puppet::Functions.create_function(:foo) do - # @return [Undef] - dispatch :foo do - end -end + 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 - end it 'outputs a warning' do expect { spec_subject } @@ -746,17 +723,15 @@ def other(b) describe 'parsing a function with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE -# An example 4.x function. -# @summary A short summary. -Puppet::Functions.create_function(:foo) do - # @return [Undef] - dispatch :foo do - end -end + 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 - end it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -767,17 +742,15 @@ def other(b) end context 'when the summary has more than 140 characters' do - let(:source) do - <<-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 + 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 - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_function 'foo' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb index 31cf0fae3..90dfc189b 100644 --- a/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb @@ -18,12 +18,10 @@ end describe 'parsing a provider with a missing description' do - let(:source) do - <<-SOURCE -Puppet::Type.type(:custom).provide :linux do -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:custom).provide :linux do + end SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing a description for Puppet provider 'linux' \(resource type 'custom'\) at \(stdin\):1\.}).to_stdout_from_any_process @@ -31,13 +29,11 @@ end describe 'parsing a provider with an invalid docstring assignment' do - let(:source) do - <<-SOURCE -Puppet::Type.type(:custom).provide :linux do - @doc = 123 -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:custom).provide :linux do + @doc = 123 + end SOURCE - end it 'logs an error' do expect { spec_subject }.to output(%r{Failed to parse docstring}).to_stdout_from_any_process @@ -45,13 +41,11 @@ end describe 'parsing a provider with a valid docstring assignment' do - let(:source) do - <<-SOURCE -Puppet::Type.type(:custom).provide :linux do - @doc = 'An example provider on Linux.' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:custom).provide :linux do + @doc = 'An example provider on Linux.' + end SOURCE - end it 'correctlies detect the docstring' do expect(spec_subject.size).to eq(1) @@ -61,15 +55,13 @@ end describe 'parsing a provider with a docstring which uses ruby `%Q` notation' do - let(:source) do - <<-'SOURCE' -Puppet::Type.type(:custom).provide :linux do - test = 'hello world!' - desc %Q{This is a multi-line - doc in %Q with #{test}} -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:custom).provide :linux do + test = 'hello world!' + desc %Q{This is a multi-line + doc in %Q with #{test}} + end SOURCE - end it 'strips the `%Q{}` and render the interpolation expression literally' do expect(spec_subject.size).to eq(1) @@ -79,20 +71,18 @@ end describe 'parsing a provider definition' do - let(:source) do - <<-SOURCE -Puppet::Type.type(:custom).provide :linux do - desc 'An example provider on Linux.' - confine kernel: 'Linux' - confine osfamily: 'RedHat' - defaultfor :kernel => 'Linux' - defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7' - has_feature :implements_some_feature - has_feature :some_other_feature - commands foo: '/usr/bin/foo' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:custom).provide :linux do + desc 'An example provider on Linux.' + confine kernel: 'Linux' + confine osfamily: 'RedHat' + defaultfor :kernel => 'Linux' + defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7' + has_feature :implements_some_feature + has_feature :some_other_feature + commands foo: '/usr/bin/foo' + end SOURCE - end it 'registers a provider object' do expect(spec_subject.size).to eq(1) @@ -114,13 +104,11 @@ end describe 'parsing a provider definition with a string based name' do - let(:source) do - <<-SOURCE -Puppet::Type.type(:'custom').provide :'linux' do - desc 'An example provider on Linux.' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:'custom').provide :'linux' do + desc 'An example provider on Linux.' + end SOURCE - end it 'registers a provider object' do expect(spec_subject.size).to eq(1) @@ -135,13 +123,11 @@ describe 'parsing a provider with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE -Puppet::Type.type(:custom).provide :linux do - @doc = '@summary A short summary.' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:custom).provide :linux do + @doc = '@summary A short summary.' + end SOURCE - end it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -152,13 +138,11 @@ end context 'when the summary has more than 140 characters' do - let(:source) do - <<-SOURCE -Puppet::Type.type(:custom).provide :linux do - @doc = '@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!!' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.type(:custom).provide :linux do + @doc = '@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!!' + end SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_provider 'linux' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb index b5f1c3d68..e1c841ce8 100644 --- a/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb @@ -18,13 +18,11 @@ end describe 'parsing a type with a missing description' do - let(:source) do - <<-SOURCE -Puppet::ResourceApi.register_type( - name: 'database' -) + let(:source) { <<~'SOURCE' } + Puppet::ResourceApi.register_type( + name: 'database' + ) SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing a description for Puppet resource type 'database' at \(stdin\):1\.}).to_stdout_from_any_process @@ -32,14 +30,12 @@ end describe 'parsing a type with a valid docstring assignment' do - let(:source) do - <<-SOURCE -Puppet::ResourceApi.register_type( - name: 'database', - docs: 'An example database server resource type.', -) + let(:source) { <<~'SOURCE' } + Puppet::ResourceApi.register_type( + name: 'database', + docs: 'An example database server resource type.', + ) SOURCE - end it 'correctlies detect the docstring' do expect(spec_subject.size).to eq(1) @@ -49,17 +45,15 @@ end describe 'parsing a type with a docstring which uses ruby `%Q` notation' do - let(:source) do - <<-'SOURCE' -test = 'hello world!' - -Puppet::ResourceApi.register_type( - name: 'database', - docs: %Q{This is a multi-line -doc in %Q with #{test}}, -) + let(:source) { <<~'SOURCE' } + test = 'hello world!' + + Puppet::ResourceApi.register_type( + name: 'database', + docs: %Q{This is a multi-line + doc in %Q with #{test}}, + ) SOURCE - end it 'strips the `%Q{}` and render the interpolation expression literally' do expect(spec_subject.size).to eq(1) @@ -69,55 +63,53 @@ end describe 'parsing a type definition' do - let(:source) do - <<-SOURCE -# @!puppet.type.param [value1, value2] dynamic_param Documentation for a dynamic parameter. -# @!puppet.type.property [foo, bar] dynamic_prop Documentation for a dynamic property. -Puppet::ResourceApi.register_type( - name: 'database', - docs: 'An example database server resource type.', - features: ['remote-resource'], - attributes: { - ensure: { - type: 'Enum[present, absent, up, down]', - desc: 'What state the database should be in.', - default: 'up', - }, - address: { - type: 'String', - desc: 'The database server name.', - behaviour: :namevar, - }, - encrypt: { - type: 'Boolean', - desc: 'Whether or not to encrypt the database.', - default: false, - behaviour: :parameter, - }, - encryption_key: { - type: 'Optional[String]', - desc: 'The encryption key to use.', - behaviour: :parameter, - }, - backup: { - type: 'Enum[daily, monthly, never]', - desc: 'How often to backup the database.', - default: 'never', - behaviour: :parameter, - }, - file: { - type: 'String', - desc: 'The database file to use.', - }, - log_level: { - type: 'Enum[debug, warn, error]', - desc: 'The log level to use.', - default: 'warn', - }, - }, -) + let(:source) { <<~'SOURCE' } + # @!puppet.type.param [value1, value2] dynamic_param Documentation for a dynamic parameter. + # @!puppet.type.property [foo, bar] dynamic_prop Documentation for a dynamic property. + Puppet::ResourceApi.register_type( + name: 'database', + docs: 'An example database server resource type.', + features: ['remote-resource'], + attributes: { + ensure: { + type: 'Enum[present, absent, up, down]', + desc: 'What state the database should be in.', + default: 'up', + }, + address: { + type: 'String', + desc: 'The database server name.', + behaviour: :namevar, + }, + encrypt: { + type: 'Boolean', + desc: 'Whether or not to encrypt the database.', + default: false, + behaviour: :parameter, + }, + encryption_key: { + type: 'Optional[String]', + desc: 'The encryption key to use.', + behaviour: :parameter, + }, + backup: { + type: 'Enum[daily, monthly, never]', + desc: 'How often to backup the database.', + default: 'never', + behaviour: :parameter, + }, + file: { + type: 'String', + desc: 'The database file to use.', + }, + log_level: { + type: 'Enum[debug, warn, error]', + desc: 'The log level to use.', + default: 'warn', + }, + }, + ) SOURCE - end it 'registers a type object' do expect(spec_subject.size).to eq(1) @@ -187,14 +179,12 @@ describe 'parsing a type with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE -Puppet::ResourceApi.register_type( - name: 'database', - docs: '@summary A short summary.', -) + let(:source) { <<~'SOURCE' } + Puppet::ResourceApi.register_type( + name: 'database', + docs: '@summary A short summary.', + ) SOURCE - end it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -205,14 +195,12 @@ end context 'when the summary has more than 140 characters' do - let(:source) do - <<-SOURCE -Puppet::ResourceApi.register_type( - name: 'database', - docs: '@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!!', -) + let(:source) { <<~'SOURCE' } + Puppet::ResourceApi.register_type( + name: 'database', + docs: '@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!!', + ) SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_type 'database' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process @@ -221,20 +209,18 @@ end describe 'parsing a type with title_patterns' do - let(:source) do - <<-SOURCE -Puppet::ResourceApi.register_type( - name: 'database', - docs: 'An example database server resource type.', - title_patterns: [ - { - pattern: %r{(?.*)}, - desc: 'Generic title match', - } - ] -) + let(:source) { <<~'SOURCE' } + Puppet::ResourceApi.register_type( + name: 'database', + docs: 'An example database server resource type.', + title_patterns: [ + { + pattern: %r{(?.*)}, + desc: 'Generic title match', + } + ] + ) SOURCE - end it 'does not emit a warning' do expect { spec_subject }.not_to output(%r{\[warn\].*unexpected construct regexp_literal}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/type_extras_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/type_extras_handler_spec.rb index ada072717..a79239edc 100644 --- a/spec/unit/puppet-strings/yard/handlers/ruby/type_extras_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/ruby/type_extras_handler_spec.rb @@ -10,8 +10,7 @@ end describe 'parsing source with newproperty' do - let(:source) do - <<~SOURCE + let(:source) { <<~'SOURCE' } Puppet::Type.newtype(:database) do desc 'database' end @@ -19,7 +18,6 @@ desc 'The database file to use.' end SOURCE - end it 'generates a doc string for a property' do expect(spec_subject.size).to eq(1) @@ -31,8 +29,7 @@ end describe 'parsing source with newparam' do - let(:source) do - <<~SOURCE + let(:source) { <<~'SOURCE' } Puppet::Type.newtype(:database) do desc 'database' end @@ -40,7 +37,6 @@ desc 'The database server name.' end SOURCE - end it 'generates a doc string for a parameter that is also a namevar' do expect(spec_subject.size).to eq(1) @@ -53,8 +49,7 @@ end describe 'parsing source with ensurable' do - let(:source) do - <<~SOURCE + let(:source) { <<~'SOURCE' } Puppet::Type.newtype(:database) do desc 'database' end @@ -62,7 +57,6 @@ desc 'What state the database should be in.' end SOURCE - end it 'generates a doc string for an ensurable' do expect(spec_subject.size).to eq(1) diff --git a/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb b/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb index 604912b4f..db0e402a2 100644 --- a/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb +++ b/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb @@ -18,12 +18,10 @@ end describe 'parsing a type with a missing description' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + end SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: Missing a description for Puppet resource type 'database' at \(stdin\):1\.}).to_stdout_from_any_process @@ -31,13 +29,11 @@ end describe 'parsing a type with an invalid docstring assignment' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do - @doc = 123 -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + @doc = 123 + end SOURCE - end it 'logs an error' do expect { spec_subject }.to output(%r{Failed to parse docstring}).to_stdout_from_any_process @@ -45,13 +41,11 @@ end describe 'parsing a type with a valid docstring assignment' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do - @doc = 'An example database server resource type.' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + @doc = 'An example database server resource type.' + end SOURCE - end it 'correctlies detect the docstring' do expect(spec_subject.size).to eq(1) @@ -61,15 +55,13 @@ end describe 'parsing a type with a docstring which uses ruby `%Q` notation' do - let(:source) do - <<-'SOURCE' -Puppet::Type.newtype(:database) do - test = 'hello world!' - desc %Q{This is a multi-line - doc in %Q with #{test}} -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + test = 'hello world!' + desc %Q{This is a multi-line + doc in %Q with #{test}} + end SOURCE - end it 'strips the `%Q{}` and render the interpolation expression literally' do expect(spec_subject.size).to eq(1) @@ -79,18 +71,16 @@ end describe 'parsing a type with a param with arguments' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do - feature :encryption, 'The provider supports encryption.', methods: [:encrypt] - - newparam(:encryption_key, :parent => Puppet::Parameter::Boolean, required_features: :encryption) do - desc 'The encryption key to use.' - defaultto false - end -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + feature :encryption, 'The provider supports encryption.', methods: [:encrypt] + + newparam(:encryption_key, :parent => Puppet::Parameter::Boolean, required_features: :encryption) do + desc 'The encryption key to use.' + defaultto false + end + end SOURCE - end it 'correctlies detect the required_feature' do expect(spec_subject.size).to eq(1) @@ -106,60 +96,58 @@ end describe 'parsing a type definition' do - let(:source) do - <<-SOURCE -# @!puppet.type.param [value1, value2] dynamic_param Documentation for a dynamic parameter. -# @!puppet.type.property [foo, bar] dynamic_prop Documentation for a dynamic property. -Puppet::Type.newtype(:database) do - desc 'An example database server resource type.' - feature :encryption, 'The provider supports encryption.', methods: [:encrypt] - - feature :magic, - 'The feature docstring should have - whitespace and newlines stripped out.' - - ensurable do - desc 'What state the database should be in.' - defaultvalues - aliasvalue(:up, :present) - aliasvalue(:down, :absent) - defaultto :up - end - - newparam(:address) do - isnamevar - desc 'The database server name.' - end - - newparam(:encryption_key, required_features: :encryption) do - desc 'The encryption key to use.' - end - - newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do - desc 'Whether or not to encrypt the database.' - defaultto false - end - - newparam(:backup) do - desc 'How often to backup the database.' - defaultto :never - newvalues(:daily, :monthly, :never) - end - - newproperty(:file) do - desc 'The database file to use.' - end - - newproperty(:log_level) do - desc 'The log level to use.' - newvalue(:debug) - newvalue(:warn) - newvalue(:error) - defaultto 'warn' - end -end + let(:source) { <<~'SOURCE' } + # @!puppet.type.param [value1, value2] dynamic_param Documentation for a dynamic parameter. + # @!puppet.type.property [foo, bar] dynamic_prop Documentation for a dynamic property. + Puppet::Type.newtype(:database) do + desc 'An example database server resource type.' + feature :encryption, 'The provider supports encryption.', methods: [:encrypt] + + feature :magic, + 'The feature docstring should have + whitespace and newlines stripped out.' + + ensurable do + desc 'What state the database should be in.' + defaultvalues + aliasvalue(:up, :present) + aliasvalue(:down, :absent) + defaultto :up + end + + newparam(:address) do + isnamevar + desc 'The database server name.' + end + + newparam(:encryption_key, required_features: :encryption) do + desc 'The encryption key to use.' + end + + newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do + desc 'Whether or not to encrypt the database.' + defaultto false + end + + newparam(:backup) do + desc 'How often to backup the database.' + defaultto :never + newvalues(:daily, :monthly, :never) + end + + newproperty(:file) do + desc 'The database file to use.' + end + + newproperty(:log_level) do + desc 'The log level to use.' + newvalue(:debug) + newvalue(:warn) + newvalue(:error) + defaultto 'warn' + end + end SOURCE - end it 'registers a type object' do expect(spec_subject.size).to eq(1) @@ -232,14 +220,12 @@ end describe 'parsing a valid type with string based name' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:'database') do - desc 'An example database server resource type.' - ensurable -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:'database') do + desc 'An example database server resource type.' + ensurable + end SOURCE - end it 'registers a type object with default ensure values' do expect(spec_subject.size).to eq(1) @@ -249,14 +235,12 @@ end describe 'parsing an ensurable type with default ensure values' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do - desc 'An example database server resource type.' - ensurable -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + desc 'An example database server resource type.' + ensurable + end SOURCE - end it 'registers a type object with default ensure values' do expect(spec_subject.size).to eq(1) @@ -269,16 +253,14 @@ end describe 'parsing a type with a parameter with the name of "name"' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do - desc 'An example database server resource type.' - newparam(:name) do - desc 'The database server name.' - end -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + desc 'An example database server resource type.' + newparam(:name) do + desc 'The database server name.' + end + end SOURCE - end it 'registers a type object with the "name" parameter as the namevar' do expect(spec_subject.size).to eq(1) @@ -290,16 +272,14 @@ end describe 'parsing a type with a check with the name of "onlyif"' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:testexec) do - desc 'An example exec type with a check.' - newcheck(:onlyif) do - desc 'a test check param' - end -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:testexec) do + desc 'An example exec type with a check.' + newcheck(:onlyif) do + desc 'a test check param' + end + end SOURCE - end it 'registers a check object on the parent type object' do expect(spec_subject.size).to eq(1) @@ -311,13 +291,11 @@ describe 'parsing a type with a summary' do context 'when the summary has fewer than 140 characters' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do - @doc = '@summary A short summary.' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + @doc = '@summary A short summary.' + end SOURCE - end it 'parses the summary' do expect { spec_subject }.to output('').to_stdout_from_any_process @@ -328,13 +306,11 @@ end context 'when the summary has more than 140 characters' do - let(:source) do - <<-SOURCE -Puppet::Type.newtype(:database) do - @doc = '@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!!' -end + let(:source) { <<~'SOURCE' } + Puppet::Type.newtype(:database) do + @doc = '@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!!' + end SOURCE - end it 'logs a warning' do expect { spec_subject }.to output(%r{\[warn\]: The length of the summary for puppet_type 'database' exceeds the recommended limit of 140 characters.}).to_stdout_from_any_process diff --git a/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb b/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb index b378aceb0..264eab6d7 100644 --- a/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb +++ b/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb @@ -27,11 +27,9 @@ end describe 'parsing invalid JSON' do - let(:source) do - < present - } -} -SOURCE - end + let(:source) { <<~'SOURCE' } + notice hello + # A simple foo class. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { + file { '/tmp/foo': + ensure => present + } + } + SOURCE it 'onlies return the class statement' do spec_subject.parse @@ -78,14 +74,12 @@ class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar { end describe 'parsing nested class definitions' do - let(:source) do - < present - } -} -SOURCE - end + let(:source) { <<~'SOURCE' } + notice hello + # A simple foo defined type. + # @param param1 First param. + # @param param2 Second param. + # @param param3 Third param. + define foo(Integer $param1, $param2, String $param3 = hi) { + file { '/tmp/foo': + ensure => present + } + } + SOURCE it 'parses the defined type statement' do spec_subject.parse @@ -177,18 +169,16 @@ class bar { end describe 'parsing puppet functions', if: TEST_PUPPET_FUNCTIONS do - let(:source) do - <> String { - notice world - } -SOURCE - end + let(:source) { <<~'SOURCE' } + # A simple foo function. + # @return Returns a string + function foo() >> String { + notice world + } + SOURCE it 'parses the puppet function statement' do spec_subject.parse @@ -234,15 +222,13 @@ class bar { end describe 'parsing puppet functions with complex return types in defintion', if: TEST_FUNCTION_RETURN_TYPE do - let(:source) do - <> Struct[{'a' => Integer[1, 10]}] { - notice world - } -SOURCE - end + let(:source) { <<~'SOURCE' } + # A simple foo function. + # @return Returns a struct with a hash including one key which must be an integer between 1 and 10. + function foo() >> Struct[{'a' => Integer[1, 10]}] { + notice world + } + SOURCE it 'parses the puppet function statement' do spec_subject.parse @@ -255,12 +241,10 @@ class bar { describe 'parsing type alias definitions', if: TEST_PUPPET_DATATYPES do context 'given a type alias on a single line' do - let(:source) do - <<-SOURCE -# A simple foo type. -type Module::Typename = Variant[Stdlib::Windowspath, Stdlib::Unixpath] -SOURCE - end + let(:source) { <<~'SOURCE' } + # A simple foo type. + type Module::Typename = Variant[Stdlib::Windowspath, Stdlib::Unixpath] + SOURCE it 'parses the puppet type statement' do spec_subject.parse @@ -274,16 +258,14 @@ class bar { end context 'given a type alias over multiple lines' do - let(:source) do - <<-SOURCE -# A multiline foo type -# with long docs -type OptionsWithoutName = Struct[{ - value_type => Optional[ValueType], - merge => Optional[MergeType] -}] -SOURCE - end + let(:source) { <<~'SOURCE' } + # A multiline foo type + # with long docs + type OptionsWithoutName = Struct[{ + value_type => Optional[ValueType], + merge => Optional[MergeType] + }] + SOURCE it 'parses the puppet type statement' do spec_subject.parse diff --git a/spec/unit/puppet-strings/yard/util_spec.rb b/spec/unit/puppet-strings/yard/util_spec.rb index a96b8e68f..3c3673b10 100644 --- a/spec/unit/puppet-strings/yard/util_spec.rb +++ b/spec/unit/puppet-strings/yard/util_spec.rb @@ -18,9 +18,9 @@ end it 'does not affect newlines when %Q notation is used' do - str = <<-STR -%Q{this is -a test string} + str = <<~'STR' + %Q{this is + a test string} STR expect(spec_subject.scrub_string(str)).to eq("this is\na test string") end