Merge pull request #105 from whopper/maint/code_coverage

(PDOC-88) Add additional spec and acceptance tests

spec/acceptance/running_strings_generate.rb

@@ -14,6 +14,19 @@ describe 'Generating module documentation using generate action' do
     expect(read_file_on(master, '/root/doc/puppet_classes/test.html')).to include('Class: test')
   end
 
+  it 'should generate documentation for puppet functions' do
+    puppet_version = on(master, facter('puppetversion')).stdout.chomp.to_i
+
+    if puppet_version >= 4
+      html_output = read_file_on(master, '/root/doc/puppet_functions_puppet/test_3A_3Aadd.html')
+      expect(html_output).to include('Adds two integers together.')
+      expect(html_output).to include('<pre class="example code"><code>test::add(1, 2) =&gt; 3</code></pre>')
+      expect(html_output).to include('<p>The first integer to add.</p>')
+      expect(html_output).to include('<p>The second integer to add.</p>')
+      expect(html_output).to include('<p>Returns the sum of x and y.</p>')
+    end
+  end
+
   it 'should generate documentation for 3x functions' do
     expect(read_file_on(master, '/root/doc/puppet_functions_ruby3x/function3x.html')).to include('This is the function documentation for <code>function3x</code>')
   end
@@ -21,4 +34,21 @@ describe 'Generating module documentation using generate action' do
   it 'should generate documentation for 4x functions' do
     expect(read_file_on(master, '/root/doc/puppet_functions_ruby4x/function4x.html')).to include('This is a function which is used to test puppet strings')
   end
+
+  it 'should generate documentation for custom types' do
+    html_output = read_file_on(master, '/root/doc/puppet_types/database.html')
+    expect(html_output).to include('<p>An example server resource type.</p>')
+    expect(html_output).to include('<p>The database file to use.</p>')
+    expect(html_output).to include('<p>Documentation for a dynamic property.</p>')
+    expect(html_output).to include('<p>The database server name.</p>')
+    expect(html_output).to include('<p>Documentation for a dynamic parameter.</p>')
+    expect(html_output).to include('<p>The provider supports encryption.</p>')
+  end
+
+  it 'should generate documentation for custom providers' do
+    html_output = read_file_on(master, '/root/doc/puppet_providers_database/linux.html')
+    expect(html_output).to include('The database provider on Linux')
+    expect(html_output).to include('<tt>osfamily &mdash; linux</tt>')
+    expect(html_output).to include('<tt>database &mdash; /usr/bin/database</tt>')
+  end
 end

spec/fixtures/acceptance/modules/test/functions/add.pp

@@ -0,0 +1,9 @@
+# Adds two integers together.
+# @param x The first integer to add.
+# @param y The second integer to add.
+# @return [Integer] Returns the sum of x and y.
+# @example Example of adding two integers.
+#   test::add(1, 2) => 3
+function test::add(Integer $x, Integer $y) {
+  $x + $y
+}

spec/fixtures/acceptance/modules/test/lib/puppet/provider/server/linux.rb

@@ -0,0 +1,9 @@
+Puppet::Type.type(:database).provide :linux do
+  confine 'osfamily' => 'linux'
+  defaultfor 'osfamily' => 'linux'
+  commands :database => '/usr/bin/database'
+
+  desc 'The database provider on Linux.'
+
+  # ...
+end

spec/fixtures/acceptance/modules/test/lib/puppet/type/database.rb

@@ -0,0 +1,15 @@
+# @!puppet.type.param [value1, value2, value3] my_param Documentation for a dynamic parameter.
+# @!puppet.type.property [foo, bar, baz] my_prop Documentation for a dynamic property.
+Puppet::Type.newtype(:database) do
+  desc 'An example server resource type.'
+  feature :encryption, 'The provider supports encryption.', methods: [:encrypt]
+
+  newparam(:address) do
+    isnamevar
+    desc 'The database server name.'
+  end
+
+  newproperty(:file) do
+    desc 'The database file to use.'
+  end
+end

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

@@ -27,6 +27,34 @@ SOURCE
     end
   end
 
+  describe 'parsing a provider with an invalid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+  @doc = 123
+end
+SOURCE
+    }
+
+    it 'should log an error' do
+      expect { subject }.to output(/Failed to parse docstring/).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a provider with a valid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.type(:custom).provide :linux do
+  @doc = 'An example provider on Linux.'
+end
+SOURCE
+    }
+
+    it 'should correctly detect the docstring' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.docstring).to eq('An example provider on Linux.')
+    end
+  end
+
   describe 'parsing a provider definition' do
     let(:source) { <<-SOURCE
 Puppet::Type.type(:custom).provide :linux do

spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb

@@ -27,8 +27,38 @@ SOURCE
     end
   end
 
+  describe 'parsing a type with an invalid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  @doc = 123
+end
+SOURCE
+    }
+
+    it 'should log an error' do
+      expect { subject }.to output(/Failed to parse docstring/).to_stdout_from_any_process
+    end
+  end
+
+  describe 'parsing a type with a valid docstring assignment' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  @doc = 'An example database server resource type.'
+end
+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 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::Type.newtype(:database) do
   desc 'An example database server resource type.'
   feature :encryption, 'The provider supports encryption.', methods: [:encrypt]
@@ -54,6 +84,12 @@ Puppet::Type.newtype(:database) do
     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
@@ -80,47 +116,99 @@ SOURCE
       tags = object.docstring.tags(:api)
       expect(tags.size).to eq(1)
       expect(tags[0].text).to eq('public')
-      expect(object.properties.size).to eq(3)
-      expect(object.properties[0].name).to eq('ensure')
-      expect(object.properties[0].docstring).to eq('What state the database should be in.')
+      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].default).to eq('up')
-      expect(object.properties[0].values).to eq(%w(present absent up down))
-      expect(object.properties[0].aliases).to eq({ 'down' => 'absent', 'up' => 'present' })
-      expect(object.properties[1].name).to eq('file')
-      expect(object.properties[1].docstring).to eq('The database file to use.')
+      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 be_nil
-      expect(object.properties[1].values).to eq([])
-      expect(object.properties[1].aliases).to eq({})
-      expect(object.properties[2].name).to eq('log_level')
-      expect(object.properties[2].docstring).to eq('The log level to use.')
+      expect(object.properties[1].default).to eq('up')
+      expect(object.properties[1].values).to eq(%w(present absent up down))
+      expect(object.properties[1].aliases).to eq({ 'down' => 'absent', 'up' => 'present' })
+      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 eq('warn')
-      expect(object.properties[2].values).to eq(%w(debug warn error))
+      expect(object.properties[2].default).to be_nil
+      expect(object.properties[2].values).to eq([])
       expect(object.properties[2].aliases).to eq({})
-      expect(object.parameters.size).to eq(3)
-      expect(object.parameters[0].name).to eq('address')
-      expect(object.parameters[0].docstring).to eq('The database server name.')
-      expect(object.parameters[0].isnamevar).to eq(true)
-      expect(object.parameters[0].default).to be_nil
-      expect(object.parameters[0].values).to eq([])
-      expect(object.parameters[0].aliases).to eq({})
-      expect(object.parameters[1].name).to eq('encryption_key')
-      expect(object.parameters[1].docstring).to eq('The encryption key to use.')
-      expect(object.parameters[1].isnamevar).to eq(false)
+      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(%w(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([])
       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].name).to eq('encryption_key')
+      expect(object.parameters[2].docstring).to eq('The encryption key to use.')
       expect(object.parameters[2].isnamevar).to eq(false)
-      expect(object.parameters[2].default).to eq('false')
-      expect(object.parameters[2].values).to eq(%w(true false yes no))
+      expect(object.parameters[2].default).to be_nil
+      expect(object.parameters[2].values).to eq([])
       expect(object.parameters[2].aliases).to eq({})
+      expect(object.parameters[3].name).to eq('encrypt')
+      expect(object.parameters[3].docstring).to eq('Whether or not to encrypt the database.')
+      expect(object.parameters[3].isnamevar).to eq(false)
+      expect(object.parameters[3].default).to eq('false')
+      expect(object.parameters[3].values).to eq(%w(true false yes no))
+      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(%w(daily monthly never))
       expect(object.features.size).to eq(1)
       expect(object.features[0].name).to eq('encryption')
       expect(object.features[0].docstring).to eq('The provider supports encryption.')
     end
   end
+
+  describe 'parsing an ensurable type with default ensure values' do
+    let(:source) { <<-SOURCE
+Puppet::Type.newtype(:database) do
+  desc 'An example database server resource type.'
+  ensurable
+end
+SOURCE
+    }
+
+    it 'should register a type object with default ensure values' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.properties[0].name).to eq('ensure')
+      expect(object.properties[0].docstring).to eq('The basic property that the resource should be in.')
+      expect(object.properties[0].default).to eq('present')
+      expect(object.properties[0].values).to eq(%w(present absent))
+    end
+  end
+
+  describe 'parsing a type with a parameter with the name of "name"' do
+    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
+    }
+
+    it 'should register a type object with the "name" parameter as the namevar' do
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object.parameters.size).to eq(1)
+      expect(object.parameters[0].name).to eq('name')
+      expect(object.parameters[0].isnamevar).to eq(true)
+    end
+  end
 end