puppet-strings 1.1.1 → 1.2.0

data/spec/unit/puppet-strings/markdown/base_spec.rb

@@ -0,0 +1,146 @@
+require 'spec_helper'
+
+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 {
+}
+SOURCE
+    end
+
+    let(:reg) { YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)[0] }
+    let(:component) { PuppetStrings::Markdown::Base.new(reg, 'class') }
+
+    describe '#name' do
+      it 'returns the expected name' do
+        expect(component.name).to eq 'klass'
+      end
+    end
+
+    [ 'examples',
+      'see',
+      'since',
+      'return_val',
+      'return_type',].each do |method|
+      describe "##{method}" do
+        it 'returns nil' do
+          expect(component.method(method.to_sym).call).to be_nil
+        end
+      end
+
+    end
+
+    describe '#private?' do
+      it do
+        expect(component.private?).to be true
+      end
+    end
+
+    describe '#params' do
+      it 'returns the expected params' do
+        expect(component.params.size).to eq 3
+      end
+    end
+
+    describe '#summary' do
+      it 'returns the expected summary' do
+        expect(component.summary).to eq 'A simple class.'
+      end
+    end
+
+    describe '#toc_info' do
+      let(:toc) { component.toc_info }
+      it 'returns a hash' do
+        expect(toc).to be_instance_of Hash
+      end
+      it 'prefers the summary for :desc' do
+        expect(toc[:desc]).to eq 'A simple class.'
+      end
+    end
+  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 {
+
+}
+SOURCE
+    end
+
+    let(:reg) { YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)[0] }
+    let(:component) { PuppetStrings::Markdown::Base.new(reg, 'class') }
+
+    describe '#name' do
+      it 'returns the expected name' do
+        expect(component.name).to eq 'klass::yeah'
+      end
+    end
+
+    ['summary',
+      'see',
+      'since',
+      'return_val',
+      'return_type'].each do |method|
+      describe "##{method}" do
+        it 'returns nil' do
+          expect(component.method(method.to_sym).call).to be_nil
+        end
+      end
+    end
+
+    describe '#examples' do
+      it 'should return one example' do
+        expect(component.examples.size).to eq 1
+      end
+    end
+
+    describe '#params' do
+      it 'returns the expected params' do
+        expect(component.params.size).to eq 3
+      end
+    end
+
+    describe '#private?' do
+      it do
+        expect(component.private?).to be false
+      end
+    end
+
+    describe '#toc_info' do
+      let(:toc) { component.toc_info }
+      it 'returns a hash' do
+        expect(toc).to be_instance_of Hash
+      end
+      it 'uses overview for :desc in absence of summary' do
+        expect(toc[:desc]).to eq 'An overview It\'s a longer overview Ya know?'
+      end
+    end
+
+    describe '#link' do
+      it 'returns a valid link' do
+        expect(component.link).to eq 'klassyeah'
+      end
+    end
+  end
+end

data/spec/unit/puppet-strings/markdown_spec.rb

@@ -0,0 +1,248 @@
+require 'spec_helper'
+require 'puppet-strings/markdown'
+require 'puppet-strings/markdown/table_of_contents'
+require 'tempfile'
+
+describe PuppetStrings::Markdown do
+  before :each do
+    # Populate the YARD registry with both Puppet and Ruby source
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
+# An overview for a simple class.
+# @summary A simple class.
+# @since 1.0.0
+# @see www.puppet.com
+# @example This is an example
+#  class { 'klass':
+#    param1 => 1,
+#    param3 => 'foo',
+#  }
+# @example This is another example
+#  class { 'klass':
+#    param1 => 1,
+#    param3 => 'foo',
+#  }
+# @raise SomeError
+# @param param1 First param.
+# @param param2 Second param.
+# @option param2 [String] :opt1 something about opt1
+# @option param2 [Hash] :opt2 a hash of stuff
+# @param param3 Third param.
+#
+class klass (
+  Integer $param1 = 1,
+  $param2 = undef,
+  String $param3 = 'hi'
+) inherits foo::bar {
+}
+
+# Overview for class noparams
+# @api private
+class noparams () {}
+
+# An overview for a simple defined type.
+# @summary A simple defined type.
+# @since 1.1.0
+# @see www.puppet.com
+# @example Here's an example of this type:
+#  klass::dt { 'foo':
+#    param1 => 33,
+#    param4 => false,
+#  }
+# @return shouldn't return squat
+# @raise SomeError
+# @param param1 First param.
+# @param param2 Second param.
+# @option param2 [String] :opt1 something about opt1
+# @option param2 [Hash] :opt2 a hash of stuff
+# @param param3 Third param.
+# @param param4 Fourth param.
+define klass::dt (
+  Integer $param1 = 44,
+  $param2,
+  String $param3 = 'hi',
+  Boolean $param4 = true
+) {
+}
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
+# A simple Puppet function.
+# @param param1 First param.
+# @param param2 Second param.
+# @param param3 Third param.
+# @option param3 [Array] :param3opt Something about this option
+# @raise SomeError this is some error
+# @return [Undef] Returns nothing.
+function func(Integer $param1, $param2, String $param3 = hi) {
+}
+SOURCE
+
+    YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
+# An example 4.x function.
+Puppet::Functions.create_function(:func4x) do
+  # An overview for the first overload.
+  # @raise SomeError this is some error
+  # @param param1 The first parameter.
+  # @param param2 The second parameter.
+  # @option param2 [String] :option an option
+  # @option param2 [String] :option2 another option
+  # @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
+
+  # An overview for the second overload.
+  # @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
+
+# 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|
+   #...
+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 <<-DESC
+An example database server type.
+@option opts :foo bar
+@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.'
+    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',
+  desc: <<-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
+
+  let(:filename) { 'output.md' }
+  let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/markdown/#{filename}") }
+  let(:baseline) { File.read(baseline_path) }
+
+  describe 'rendering markdown to a file' do
+    it 'should output the expected markdown content' do
+      Tempfile.open('md') do |file|
+        PuppetStrings::Markdown.render(file.path)
+        expect(File.read(file.path)).to eq(baseline)
+      end
+    end
+  end
+
+  describe 'rendering markdown to stdout' do
+    it 'should output the expected markdown content' do
+      expect{ PuppetStrings::Markdown.render }.to output(baseline).to_stdout
+    end
+  end
+end

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

@@ -20,7 +20,7 @@ describe PuppetStrings::Yard::Handlers::Puppet::FunctionHandler, if: TEST_PUPPET
     let(:source) { 'function foo{' }
 
     it 'should log an error' do
-      expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of file/).to_stdout_from_any_process
+      expect{ subject }.to output(/\[error\]: Failed to parse \(stdin\): Syntax error at end of/).to_stdout_from_any_process
       expect(subject.empty?).to eq(true)
     end
   end
@@ -216,6 +216,21 @@ SOURCE
     end
   end
 
+  describe 'parsing a function with a non-conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do
+    let(:source) { <<-SOURCE
+# A simple foo function
+# @return [String] Hi there
+function foo() >> String {
+  notice 'hi there'
+}
+SOURCE
+    }
+
+    it 'should not output a warning if return types match' do
+      expect{ subject }.not_to output(/Documented return type does not match return type in function definition/).to_stdout_from_any_process
+    end
+  end
+
   describe 'parsing a function with a conflicting return tag and type in function definition', if: TEST_FUNCTION_RETURN_TYPE do
     let(:source) { <<-SOURCE
 # A simple foo function.

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

@@ -82,7 +82,7 @@ Puppet::Type.type(:custom).provide :linux do
   defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7'
   has_feature :implements_some_feature
   has_feature :some_other_feature
-  commands foo: /usr/bin/foo
+  commands foo: '/usr/bin/foo'
 end
 SOURCE
     }

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

@@ -0,0 +1,213 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Handlers::Ruby::RsapiHandler do
+  subject {
+    YARD::Parser::SourceParser.parse_string(source, :ruby)
+    YARD::Registry.all(:puppet_type)
+  }
+
+  describe 'parsing source without a type definition' do
+    let(:source) { 'puts "hi"' }
+
+    it 'no types should be in the registry' do
+      expect(subject.empty?).to eq(true)
+    end
+  end
+
+  describe 'parsing a type with a missing description' do
+    let(:source) { <<-SOURCE
+Puppet::ResourceApi.register_type(
+  name: 'database'
+)
+SOURCE
+    }
+
+    it 'should log a warning' do
+      expect{ subject }.to output(/\[warn\]: Missing a description for Puppet resource type 'database' at \(stdin\):1\./).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a type with a valid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::ResourceApi.register_type(
+  name: 'database',
+  docs: 'An example database server resource type.',
+)
+SOURCE
+    }
+
+    it 'should correctly detect the docstring' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.docstring).to eq('An example database server resource type.')
+    end
+  end
+
+  describe 'parsing a type with a docstring which uses ruby `%Q` notation' do
+    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
+    }
+
+    it 'should strip the `%Q{}` and render the interpolation expression literally' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.docstring).to eq("This is a multi-line\ndoc in %Q with \#{test}")
+    end
+  end
+
+  describe 'parsing a type definition' do
+    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.',
+  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
+    }
+
+    it 'should register a type object' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Type)
+      expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Types.instance)
+      expect(object.name).to eq(:database)
+      expect(object.docstring).to eq('An example database server resource type.')
+      expect(object.docstring.tags.size).to eq(1)
+      tags = object.docstring.tags(:api)
+      expect(tags.size).to eq(1)
+      expect(tags[0].text).to eq('public')
+      expect(object.properties.map(&:name)).to eq(['dynamic_prop', 'ensure', 'file', 'log_level'])
+      expect(object.properties.size).to eq(4)
+      expect(object.properties[0].name).to eq('dynamic_prop')
+      expect(object.properties[0].docstring).to eq('Documentation for a dynamic property.')
+      expect(object.properties[0].isnamevar).to eq(false)
+      expect(object.properties[0].values).to eq(%w(foo bar))
+      expect(object.properties[1].name).to eq('ensure')
+      expect(object.properties[1].docstring).to eq('What state the database should be in.')
+      expect(object.properties[1].isnamevar).to eq(false)
+      expect(object.properties[1].default).to eq('up')
+      expect(object.properties[1].values).to eq(['Enum[present, absent, up, down]'])
+      expect(object.properties[1].aliases).to eq({})
+      expect(object.properties[2].name).to eq('file')
+      expect(object.properties[2].docstring).to eq('The database file to use.')
+      expect(object.properties[2].isnamevar).to eq(false)
+      expect(object.properties[2].default).to be_nil
+      expect(object.properties[2].values).to eq(['String'])
+      expect(object.properties[2].aliases).to eq({})
+      expect(object.properties[3].name).to eq('log_level')
+      expect(object.properties[3].docstring).to eq('The log level to use.')
+      expect(object.properties[3].isnamevar).to eq(false)
+      expect(object.properties[3].default).to eq('warn')
+      expect(object.properties[3].values).to eq(['Enum[debug, warn, error]'])
+      expect(object.properties[3].aliases).to eq({})
+      expect(object.parameters.size).to eq(5)
+      expect(object.parameters[0].name).to eq('dynamic_param')
+      expect(object.parameters[0].docstring).to eq('Documentation for a dynamic parameter.')
+      expect(object.parameters[0].isnamevar).to eq(false)
+      expect(object.parameters[0].values).to eq(%w(value1 value2))
+      expect(object.parameters[1].name).to eq('address')
+      expect(object.parameters[1].docstring).to eq('The database server name.')
+      expect(object.parameters[1].isnamevar).to eq(true)
+      expect(object.parameters[1].default).to be_nil
+      expect(object.parameters[1].values).to eq(['String'])
+      expect(object.parameters[1].aliases).to eq({})
+      expect(object.parameters[2].name).to eq('encrypt')
+      expect(object.parameters[2].docstring).to eq('Whether or not to encrypt the database.')
+      expect(object.parameters[2].isnamevar).to eq(false)
+      expect(object.parameters[2].default).to eq(false)
+      expect(object.parameters[2].values).to eq(["Boolean"])
+      expect(object.parameters[2].aliases).to eq({})
+      expect(object.parameters[3].name).to eq('encryption_key')
+      expect(object.parameters[3].docstring).to eq('The encryption key to use.')
+      expect(object.parameters[3].isnamevar).to eq(false)
+      expect(object.parameters[3].default).to be_nil
+      expect(object.parameters[3].values).to eq(["Optional[String]"])
+      expect(object.parameters[3].aliases).to eq({})
+      expect(object.parameters[4].name).to eq('backup')
+      expect(object.parameters[4].docstring).to eq('How often to backup the database.')
+      expect(object.parameters[4].isnamevar).to eq(false)
+      expect(object.parameters[4].default).to eq('never')
+      expect(object.parameters[4].values).to eq(["Enum[daily, monthly, never]"])
+    end
+  end
+
+  describe 'parsing a type with a summary' do
+    context 'when the summary has fewer than 140 characters' do
+      let(:source) { <<-SOURCE
+Puppet::ResourceApi.register_type(
+  name: 'database',
+  docs: '@summary A short summary.',
+)
+SOURCE
+      }
+
+      it 'should parse the summary' do
+        expect{ subject }.to output('').to_stdout_from_any_process
+        expect(subject.size).to eq(1)
+        summary = subject.first.tags(:summary)
+        expect(summary.first.text).to eq('A short summary.')
+      end
+    end
+
+    context 'when the summary has more than 140 characters' do
+      let(:source) { <<-SOURCE
+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
+      }
+
+      it 'should log a warning' do
+        expect{ subject }.to output(/\[warn\]: The length of the summary for puppet_type 'database' exceeds the recommended limit of 140 characters./).to_stdout_from_any_process
+      end
+    end
+  end
+end