From 3f81f44df289b4c4437a5437bc51b21b78fd01a0 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Thu, 4 Sep 2014 17:04:16 -0700 Subject: [PATCH 1/8] (maint) Update .gitignore to ignore .yardoc files When YARD produces documentation, it also adds a .yardoc file. Update the .gitignore for this project to ignore these files. --- .gitignore | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.gitignore b/.gitignore index a859a2e..99e7d84 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,6 @@ tags ## BUNDLER .bundle Gemfile.lock + +## YARD +.yardoc From 7728c826158c8e741dd561c241e806447470673e Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Thu, 4 Sep 2014 20:18:16 -0700 Subject: [PATCH 2/8] (maint) Update Gemfile to require redcarpet gem Update the project Gemfile to include the redcarpet gem. This particular gem is needed for Markdown processing. --- Gemfile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Gemfile b/Gemfile index 392ea17..9c217f7 100644 --- a/Gemfile +++ b/Gemfile @@ -3,11 +3,13 @@ source 'https://rubygems.org' gem 'yard' gem 'puppet', '~> 3.6.2' gem 'rgen' +gem 'redcarpet' group :test do gem 'rspec' gem 'mocha' gem 'puppetlabs_spec_helper' + gem 'nokogiri' end group :development do From 4c303a02588557baf1862ab189a282bd0ae81df0 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Thu, 4 Sep 2014 20:23:12 -0700 Subject: [PATCH 3/8] (PDOC-2) Add tests around face and HTML generation Add tests to ensure that the face (puppet yardoc) works from end to end. In other words, ensure that when given a module, puppet yardoc can successfully evaluate the .pp and .rb files present in the module and produce the expected HTML. --- Gemfile | 1 + .../test/lib/puppet/functions/4x_function.rb | 5 ++ .../lib/puppet/parser/functions/function3x.rb | 3 + .../puppet/examples/test/manifests/init.pp | 15 +++++ spec/unit/puppet/face_spec.rb | 57 +++++++++++++++++++ 5 files changed, 81 insertions(+) create mode 100644 spec/unit/puppet/examples/test/lib/puppet/functions/4x_function.rb create mode 100644 spec/unit/puppet/examples/test/lib/puppet/parser/functions/function3x.rb diff --git a/Gemfile b/Gemfile index 9c217f7..bd32072 100644 --- a/Gemfile +++ b/Gemfile @@ -10,6 +10,7 @@ group :test do gem 'mocha' gem 'puppetlabs_spec_helper' gem 'nokogiri' + gem 'rspec-html-matchers' end group :development do diff --git a/spec/unit/puppet/examples/test/lib/puppet/functions/4x_function.rb b/spec/unit/puppet/examples/test/lib/puppet/functions/4x_function.rb new file mode 100644 index 0000000..5825496 --- /dev/null +++ b/spec/unit/puppet/examples/test/lib/puppet/functions/4x_function.rb @@ -0,0 +1,5 @@ +# function 4x +# +# This is a function which is used to test puppet strings +Puppet::Functions.create_function(:function4x) do +end diff --git a/spec/unit/puppet/examples/test/lib/puppet/parser/functions/function3x.rb b/spec/unit/puppet/examples/test/lib/puppet/parser/functions/function3x.rb new file mode 100644 index 0000000..e3083ea --- /dev/null +++ b/spec/unit/puppet/examples/test/lib/puppet/parser/functions/function3x.rb @@ -0,0 +1,3 @@ +Puppet::Parser::Functions.newfunction(:function3x, :doc => "This is the +function documentation for `function3x`") do |args| +end diff --git a/spec/unit/puppet/examples/test/manifests/init.pp b/spec/unit/puppet/examples/test/manifests/init.pp index 487cf30..8ebd451 100644 --- a/spec/unit/puppet/examples/test/manifests/init.pp +++ b/spec/unit/puppet/examples/test/manifests/init.pp @@ -1,6 +1,16 @@ +# Class: test +# +# This class exists to serve as fixture data for testing the puppet strings face +# +# @example +# class { "test": } +# +# @param package_name The name of the package +# @param service_name The name of the service class test ( $package_name = $test::params::package_name, $service_name = $test::params::service_name, + ) inherits test::params { # validate parameters here @@ -9,4 +19,9 @@ class test ( class { 'test::config': } ~> class { 'test::service': } -> Class['test'] + + File { + owner => 'user', + path => 'some/file/path', + } } diff --git a/spec/unit/puppet/face_spec.rb b/spec/unit/puppet/face_spec.rb index b60b6ef..3eaf42a 100644 --- a/spec/unit/puppet/face_spec.rb +++ b/spec/unit/puppet/face_spec.rb @@ -1,5 +1,8 @@ require 'spec_helper' require 'puppet/face/yardoc' +require 'rspec-html-matchers' +require 'tmpdir' +require 'stringio' describe Puppet::Face do @@ -27,6 +30,41 @@ describe Puppet::Face do YARD::CLI::Yardoc.expects(:run).with('--debug', 'some_file.rb') Puppet::Face[:yardoc, :current].yardoc('--debug', 'some_file.rb') end + + describe "when generating HTML for documentation" do + it "should properly generate HTML for manifest comments" do + + YARD::Logger.instance.io = StringIO.new + + using_module('test') do |tmp| + Dir.chdir('test') + + Puppet::Face[:yardoc, :current].yardoc + + expect(read_html(tmp, 'test', 'test.html')).to have_tag('.docstring .discussion', :text => /This class/) + end + end + + it "should properly generate HTML for 3x function comments" do + using_module('test') do |tmp| + Dir.chdir('test') + + Puppet::Face[:yardoc, :current].yardoc + + expect(read_html(tmp, 'test', 'ParserFunctions.html')).to have_tag('.docstring .discussion', :text => /documentation for `function3x`/) + end + end + + it "should properly generate HTML for 4x function comments" do + using_module('test') do |tmp| + Dir.chdir('test') + + Puppet::Face[:yardoc, :current].yardoc + + expect(read_html(tmp, 'test', 'test.html')).to have_tag('.docstring .discussion', :text => /This class/) + end + end + end end describe "modules action" do @@ -60,4 +98,23 @@ describe Puppet::Face do expect{Puppet::Face[:yardoc, :current].server}.to raise_error(RuntimeError, "This face requires Ruby 1.9 or greater.") end end + + # Helper methods to handle file operations around generating and loading HTML + def using_module(modulename, &block) + Dir.mktmpdir do |tmp| + module_location = File.join(File.dirname(__FILE__), "examples", modulename) + FileUtils.cp_r(module_location, tmp) + old_dir = Dir.pwd + begin + Dir.chdir(tmp) + yield(tmp) + ensure + Dir.chdir(old_dir) + end + end + end + + def read_html(dir, modulename, file) + File.read(File.join(dir, modulename, 'doc', file)) + end end From d5ffc4d8dac1b17cd180cc00118c00e8c5bdfe01 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Mon, 8 Sep 2014 15:39:31 -0700 Subject: [PATCH 4/8] (PDOC-2) Refactor tests for 4x function handler Update the spec tests which cover the Puppet 4x function handler to be more specific and cover different test cases. Prior to this commit, they would simply check that the right objects had been added to the Registry for one example. Now, they examine multiple examples and ensure that the code objects not only exist but that the details about them are what we would expect for each specific scenario. --- Gemfile | 1 - .../yardoc/yard/examples/puppet4_function.rb | 7 -- .../unit/puppetx/yardoc/yard/handlers_spec.rb | 101 ++++++++++++++++-- 3 files changed, 90 insertions(+), 19 deletions(-) delete mode 100644 spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb diff --git a/Gemfile b/Gemfile index bd32072..5fcd95e 100644 --- a/Gemfile +++ b/Gemfile @@ -9,7 +9,6 @@ group :test do gem 'rspec' gem 'mocha' gem 'puppetlabs_spec_helper' - gem 'nokogiri' gem 'rspec-html-matchers' end diff --git a/spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb b/spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb deleted file mode 100644 index fc65f89..0000000 --- a/spec/unit/puppetx/yardoc/yard/examples/puppet4_function.rb +++ /dev/null @@ -1,7 +0,0 @@ -require 'puppet' - -Puppet::Functions.create_function(:puppet4_function) do - def puppet4_function(x,y) - x >= y ? x : y - end -end diff --git a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb index adbbeb6..37098c2 100644 --- a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb +++ b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb @@ -2,6 +2,43 @@ require 'spec_helper' require 'puppetx/yardoc/yard/handlers' describe Puppetx::Yardoc::YARD::Handlers do + + # TODO: Relocate/refactor helper methods + def parse_file(file, thisfile = __FILE__, log_level = log.level, ext = '.pp') + Registry.clear + path = File.join(File.dirname(thisfile), 'examples', file.to_s + ext) + YARD::Parser::SourceParser.parse(path, [], log_level) + end + + def parse(string) + Registry.clear + YARD::Parser::SourceParser.parse_string(string) + end + + RSpec::Matchers.define :document_a do |arguments| + match do |actual| + compare_values(actual).empty? + end + + failure_message do |actual| + mismatches = compare_values(actual) + mismatches.collect do |key, value| + "Expected #{key} to be <#{value[1]}>, but got <#{value[0]}>." + end.join("\n") + end + + def compare_values(actual) + mismatched_arguments = {} + expected.each do |key, value| + actual_value = actual.send(key) + if actual_value != value + mismatched_arguments[key] = [actual_value, value] + end + end + mismatched_arguments + end + end + describe "DefinedTypeHanlder" do it "should add a defined type object in the Registry" do parse_file :defined_type, __FILE__, log.level, '.pp' @@ -11,21 +48,63 @@ describe Puppetx::Yardoc::YARD::Handlers do end describe "FutureParserDispatchHandler" do - before(:each) {parse_file :puppet4_function, __FILE__, log.level, '.rb'} - - it "should add a puppet namespace object to the Registry" do - namespace = Registry.at("FutureParserFunctions") - expect(namespace.type).to be(:puppetnamespace) + def the_method() + Registry.at("FutureParserFunctions#the_function") end - it "should add a future parser function object to the Registry" do - function = Registry.at("FutureParserFunctions#puppet4_function") - expect(function.type).to be(:method) + def the_namespace() + Registry.at("FutureParserFunctions") end - it "should add a method object to the Registry" do - method = Registry.at("#puppet4_function") - expect(method.type).to be(:method) + it "should parse single-line documentation strings before a given function" do + comment = "The summary" + parse <<-RUBY + # #{comment} + Puppet::Functions.create_function(:the_function) do + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should parse multi-line documentation strings before a given function" do + parse <<-RUBY + # The summary + # + # The longer description + Puppet::Functions.create_function(:the_function) do + end + RUBY + + comment = "The summary\n\nThe longer description" + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should not parse documentation before a function if it is followed by two new lines" do + parse <<-RUBY + # The summary + # + # The longer description + + + Puppet::Functions.create_function(:the_function) do + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => "") + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should not add anything to the Registry if incorrect ruby code is present" do + parse <<-RUBY + # The summary + Puppet::Functions.create_function(:the function do + end + RUBY + + expect(Registry.all).to be_empty end end From 74a946fcfe5c0467d01cde3e0217fb680fc0a203 Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Tue, 9 Sep 2014 11:38:41 -0700 Subject: [PATCH 5/8] (PDOC-2) Refactor tests for defined type handler Like the 4x function handler tests, the tests around the defined type handler were not very specific and didn't use multiple examples. Update the tests so that they do more than just ensure that the right objects were added to the Registry and cover a few different cases instead of just one. --- .../yardoc/yard/examples/defined_type.pp | 7 --- .../unit/puppetx/yardoc/yard/handlers_spec.rb | 59 +++++++++++++++++-- 2 files changed, 53 insertions(+), 13 deletions(-) delete mode 100644 spec/unit/puppetx/yardoc/yard/examples/defined_type.pp diff --git a/spec/unit/puppetx/yardoc/yard/examples/defined_type.pp b/spec/unit/puppetx/yardoc/yard/examples/defined_type.pp deleted file mode 100644 index 6021a41..0000000 --- a/spec/unit/puppetx/yardoc/yard/examples/defined_type.pp +++ /dev/null @@ -1,7 +0,0 @@ -define wibbly::wobbly ($wimey) { - Notify ($wimey) -} - -wibbly::wobbly{ - 'timey': wimey => stuff - } diff --git a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb index 37098c2..b317ce6 100644 --- a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb +++ b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb @@ -10,9 +10,9 @@ describe Puppetx::Yardoc::YARD::Handlers do YARD::Parser::SourceParser.parse(path, [], log_level) end - def parse(string) + def parse(string, parser = :ruby) Registry.clear - YARD::Parser::SourceParser.parse_string(string) + YARD::Parser::SourceParser.parse_string(string, parser) end RSpec::Matchers.define :document_a do |arguments| @@ -39,11 +39,58 @@ describe Puppetx::Yardoc::YARD::Handlers do end end + #TODO: Split up tests for each handler into their own files describe "DefinedTypeHanlder" do - it "should add a defined type object in the Registry" do - parse_file :defined_type, __FILE__, log.level, '.pp' - obj = Registry.at("wibbly::wobbly") - expect(obj.type).to be(:definedtype) + def the_definedtype() + Registry.at("foo::bar") + end + + it "should parse single-line documentation strings before a given defined type" do + comment = "Definition: foo::bar" + puppet_code = <<-PUPPET + # #{comment} + define foo::bar ($baz) { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_definedtype).to document_a(:type => :definedtype, :docstring => comment) + end + + it "should parse multi-line documentation strings before a given defined type" do + puppet_code = <<-PUPPET + # Definition: foo::bar + # + # This class does some stuff + define foo::bar ($baz) { } + PUPPET + + parse(puppet_code, :puppet) + + comment = "Definition: foo::bar\nThis class does some stuff" + expect(the_definedtype).to document_a(:type => :definedtype, :docstring => comment) + end + + it "should not parse documentation before a function if it is followed by a new line" do + puppet_code = <<-PUPPET + # Definition: foo::bar + + define foo::bar ($baz) { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_definedtype).to document_a(:type => :definedtype, :docstring => "") + end + it "should not add anything to the Registry if incorrect puppet code is present" do + puppet_code = <<-PUPPET + # Definition: foo::bar + This is not puppet code + PUPPET + + parse(puppet_code, :puppet) + + expect(Registry.all).to be_empty end end From 2ebde0a21e7cad412cbb7e76818429d9cdfc39ed Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Tue, 9 Sep 2014 13:43:30 -0700 Subject: [PATCH 6/8] (PDOC-2) Refactor tests for 3x function handler Rework the tests around the 3x function handler. Make them more verbose by having them them test against multiple examples and by making the checking of the Registry more details. --- .../yardoc/yard/examples/puppet3_function.rb | 7 -- .../unit/puppetx/yardoc/yard/handlers_spec.rb | 64 +++++++++++++++---- 2 files changed, 51 insertions(+), 20 deletions(-) delete mode 100644 spec/unit/puppetx/yardoc/yard/examples/puppet3_function.rb diff --git a/spec/unit/puppetx/yardoc/yard/examples/puppet3_function.rb b/spec/unit/puppetx/yardoc/yard/examples/puppet3_function.rb deleted file mode 100644 index a9e352f..0000000 --- a/spec/unit/puppetx/yardoc/yard/examples/puppet3_function.rb +++ /dev/null @@ -1,7 +0,0 @@ -require 'puppet' - -module Puppet::Parser::Functions - newfunction(:puppet3_function, :type => rvalue) do |args| - puts 'Hello World!' - end -end diff --git a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb index b317ce6..177f679 100644 --- a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb +++ b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb @@ -147,8 +147,7 @@ describe Puppetx::Yardoc::YARD::Handlers do it "should not add anything to the Registry if incorrect ruby code is present" do parse <<-RUBY # The summary - Puppet::Functions.create_function(:the function do - end + This is not ruby code RUBY expect(Registry.all).to be_empty @@ -156,21 +155,60 @@ describe Puppetx::Yardoc::YARD::Handlers do end describe "ParserFunctionHanlder" do - before(:each) {parse_file :puppet3_function, __FILE__, log.level, '.rb'} - - it "should add a module object to the Registry" do - puppet_module = Registry.at("Puppet::Parser::Functions") - expect(puppet_module.type).to be(:module) + def the_method() + Registry.at("ParserFunctions#the_function") end - it "should add a puppet namespace object to the Registry" do - namespace = Registry.at("ParserFunctions") - expect(namespace.type).to be(:puppetnamespace) + def the_namespace() + Registry.at("ParserFunctions") end - it "should add a method object to the Registry" do - method = Registry.at("ParserFunctions#puppet3_function") - expect(method.type).to be(:method) + it "should parse single-line documentation strings before a given function" do + comment = "The summary" + parse <<-RUBY + # #{comment} + newfunction(:the_function, :type => rvalue) do |args| + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should parse multi-line documentation strings before a given function" do + parse <<-RUBY + # The summary + # + # The longer description + newfunction(:the_function, :type => rvalue) do |args| + end + RUBY + + comment = "The summary\n\nThe longer description" + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should not parse documentation before a function if it is followed by two new lines" do + parse <<-RUBY + # The summary + + + newfunction(:the_function, :type => rvalue) do |args| + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => "") + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should not add anything to the Registry if incorrect ruby code is present" do + parse <<-RUBY + # The summary + This is not ruby code + RUBY + + expect(Registry.all).to be_empty end end From c56d9fc27ae1559fb8ba35891de68d5ecb76601d Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Tue, 9 Sep 2014 14:57:31 -0700 Subject: [PATCH 7/8] (PDOC-2) Refactor tests for host class handler Update the tests around the host class handler so that they test several different examples as opposed to just one. Additionally, refactor the tests so that they are more detailed when it comes to checking if the Registry is in the correct state after code has been parsed. --- .../puppetx/yardoc/yard/examples/class.pp | 5 -- .../unit/puppetx/yardoc/yard/handlers_spec.rb | 59 +++++++++++++------ 2 files changed, 40 insertions(+), 24 deletions(-) delete mode 100644 spec/unit/puppetx/yardoc/yard/examples/class.pp diff --git a/spec/unit/puppetx/yardoc/yard/examples/class.pp b/spec/unit/puppetx/yardoc/yard/examples/class.pp deleted file mode 100644 index 512b39f..0000000 --- a/spec/unit/puppetx/yardoc/yard/examples/class.pp +++ /dev/null @@ -1,5 +0,0 @@ -class foo::bar { - file { '/test/file/path': - owner => 'baz', - } -} diff --git a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb index 177f679..4ba051b 100644 --- a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb +++ b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb @@ -4,12 +4,6 @@ require 'puppetx/yardoc/yard/handlers' describe Puppetx::Yardoc::YARD::Handlers do # TODO: Relocate/refactor helper methods - def parse_file(file, thisfile = __FILE__, log_level = log.level, ext = '.pp') - Registry.clear - path = File.join(File.dirname(thisfile), 'examples', file.to_s + ext) - YARD::Parser::SourceParser.parse(path, [], log_level) - end - def parse(string, parser = :ruby) Registry.clear YARD::Parser::SourceParser.parse_string(string, parser) @@ -201,22 +195,49 @@ describe Puppetx::Yardoc::YARD::Handlers do expect(the_method).to document_a(:type => :method, :docstring => "") expect(the_namespace).to document_a(:type => :puppetnamespace) end - - it "should not add anything to the Registry if incorrect ruby code is present" do - parse <<-RUBY - # The summary - This is not ruby code - RUBY - - expect(Registry.all).to be_empty - end end describe "HostClassDefintion" do - before(:each) {parse_file :class, __FILE__, log.level, '.pp'} - it "should add a host class object to the Registry" do - hostclass = Registry.at("foo::bar") - expect(hostclass.type).to be(:hostclass) + def the_hostclass() + Registry.at("foo::bar") + end + + it "should parse single-line documentation strings before a given class" do + comment = "Class: foo::bar" + puppet_code = <<-PUPPET + # #{comment} + class foo::bar { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_hostclass).to document_a(:type => :hostclass, :docstring => comment) + end + + it "should parse multi-line documentation strings before a given class" do + puppet_code = <<-PUPPET + # Class: foo::bar + # + # This class does some stuff + class foo::bar { } + PUPPET + + parse(puppet_code, :puppet) + + comment = "Class: foo::bar\nThis class does some stuff" + expect(the_hostclass).to document_a(:type => :hostclass, :docstring => comment) + end + + it "should not parse documentation before a class if it is followed by a new line" do + puppet_code = <<-PUPPET + # Class: foo::bar + + class foo::bar { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_hostclass).to document_a(:type => :hostclass, :docstring => "") end end end From 376ceb762c2bde7ee622dec209216e4420c51def Mon Sep 17 00:00:00 2001 From: Hailee Kenney Date: Tue, 9 Sep 2014 20:43:27 -0700 Subject: [PATCH 8/8] (PDOC-2) Split up handler specs In order to make the code more readable, separate the tests into different files for each handler. Additionally, extract the helper methods into a separate module which may be included as needed. --- spec/lib/strings_spec/parsing.rb | 36 +++ spec/spec_helper.rb | 7 - .../yardoc/yard/defined_type_handler_spec.rb | 61 +++++ .../future_parser_function_handler_spec.rb | 65 +++++ .../unit/puppetx/yardoc/yard/handlers_spec.rb | 243 ------------------ .../yardoc/yard/host_class_handler_spec.rb | 49 ++++ .../yard/parser_function_handler_spec.rb | 54 ++++ 7 files changed, 265 insertions(+), 250 deletions(-) create mode 100644 spec/lib/strings_spec/parsing.rb create mode 100644 spec/unit/puppetx/yardoc/yard/defined_type_handler_spec.rb create mode 100644 spec/unit/puppetx/yardoc/yard/future_parser_function_handler_spec.rb delete mode 100644 spec/unit/puppetx/yardoc/yard/handlers_spec.rb create mode 100644 spec/unit/puppetx/yardoc/yard/host_class_handler_spec.rb create mode 100644 spec/unit/puppetx/yardoc/yard/parser_function_handler_spec.rb diff --git a/spec/lib/strings_spec/parsing.rb b/spec/lib/strings_spec/parsing.rb new file mode 100644 index 0000000..2570e28 --- /dev/null +++ b/spec/lib/strings_spec/parsing.rb @@ -0,0 +1,36 @@ +require 'spec_helper' + +module StringsSpec + module Parsing + + def parse(string, parser = :ruby) + Registry.clear + YARD::Parser::SourceParser.parse_string(string, parser) + end + + RSpec::Matchers.define :document_a do |arguments| + match do |actual| + compare_values(actual).empty? + end + + failure_message do |actual| + mismatches = compare_values(actual) + mismatches.collect do |key, value| + "Expected #{key} to be <#{value[1]}>, but got <#{value[0]}>." + end.join("\n") + end + + def compare_values(actual) + mismatched_arguments = {} + expected.each do |key, value| + actual_value = actual.send(key) + if actual_value != value + mismatched_arguments[key] = [actual_value, value] + end + end + mismatched_arguments + end + end + end +end + diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb index 311484f..7e24a2f 100644 --- a/spec/spec_helper.rb +++ b/spec/spec_helper.rb @@ -13,10 +13,3 @@ RSpec.configure do |config| config.mock_with :mocha end -# Borrowed from YARD spec helper -def parse_file(file, thisfile = __FILE__, log_level = log.level, ext = '.pp') - Registry.clear - path = File.join(File.dirname(thisfile), 'examples', file.to_s + ext) - YARD::Parser::SourceParser.parse(path, [], log_level) -end - diff --git a/spec/unit/puppetx/yardoc/yard/defined_type_handler_spec.rb b/spec/unit/puppetx/yardoc/yard/defined_type_handler_spec.rb new file mode 100644 index 0000000..7d347f2 --- /dev/null +++ b/spec/unit/puppetx/yardoc/yard/defined_type_handler_spec.rb @@ -0,0 +1,61 @@ +require 'spec_helper' +require 'puppetx/yardoc/yard/handlers/defined_type_handler' +require 'strings_spec/parsing' + + +describe "DefinedTypeHanlder" do + include StringsSpec::Parsing + + def the_definedtype() + Registry.at("foo::bar") + end + + it "should parse single-line documentation strings before a given defined type" do + comment = "Definition: foo::bar" + puppet_code = <<-PUPPET + # #{comment} + define foo::bar ($baz) { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_definedtype).to document_a(:type => :definedtype, :docstring => comment) + end + + it "should parse multi-line documentation strings before a given defined type" do + puppet_code = <<-PUPPET + # Definition: foo::bar + # + # This class does some stuff + define foo::bar ($baz) { } + PUPPET + + parse(puppet_code, :puppet) + + comment = "Definition: foo::bar\nThis class does some stuff" + expect(the_definedtype).to document_a(:type => :definedtype, :docstring => comment) + end + + it "should not parse documentation before a function if it is followed by a new line" do + puppet_code = <<-PUPPET + # Definition: foo::bar + + define foo::bar ($baz) { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_definedtype).to document_a(:type => :definedtype, :docstring => "") + end + + it "should not add anything to the Registry if incorrect puppet code is present" do + puppet_code = <<-PUPPET + # Definition: foo::bar + This is not puppet code + PUPPET + + parse(puppet_code, :puppet) + + expect(Registry.all).to be_empty + end +end diff --git a/spec/unit/puppetx/yardoc/yard/future_parser_function_handler_spec.rb b/spec/unit/puppetx/yardoc/yard/future_parser_function_handler_spec.rb new file mode 100644 index 0000000..c62bee7 --- /dev/null +++ b/spec/unit/puppetx/yardoc/yard/future_parser_function_handler_spec.rb @@ -0,0 +1,65 @@ +require 'spec_helper' +require 'puppetx/yardoc/yard/handlers/future_parser_function_handler' +require 'strings_spec/parsing' + +describe "FutureParserDispatchHandler" do + include StringsSpec::Parsing + + def the_method() + Registry.at("FutureParserFunctions#the_function") + end + + def the_namespace() + Registry.at("FutureParserFunctions") + end + + it "should parse single-line documentation strings before a given function" do + comment = "The summary" + parse <<-RUBY + # #{comment} + Puppet::Functions.create_function(:the_function) do + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should parse multi-line documentation strings before a given function" do + parse <<-RUBY + # The summary + # + # The longer description + Puppet::Functions.create_function(:the_function) do + end + RUBY + + comment = "The summary\n\nThe longer description" + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should not parse documentation before a function if it is followed by two new lines" do + parse <<-RUBY + # The summary + # + # The longer description + + + Puppet::Functions.create_function(:the_function) do + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => "") + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should not add anything to the Registry if incorrect ruby code is present" do + parse <<-RUBY + # The summary + This is not ruby code + RUBY + + expect(Registry.all).to be_empty + end +end diff --git a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb b/spec/unit/puppetx/yardoc/yard/handlers_spec.rb deleted file mode 100644 index 4ba051b..0000000 --- a/spec/unit/puppetx/yardoc/yard/handlers_spec.rb +++ /dev/null @@ -1,243 +0,0 @@ -require 'spec_helper' -require 'puppetx/yardoc/yard/handlers' - -describe Puppetx::Yardoc::YARD::Handlers do - - # TODO: Relocate/refactor helper methods - def parse(string, parser = :ruby) - Registry.clear - YARD::Parser::SourceParser.parse_string(string, parser) - end - - RSpec::Matchers.define :document_a do |arguments| - match do |actual| - compare_values(actual).empty? - end - - failure_message do |actual| - mismatches = compare_values(actual) - mismatches.collect do |key, value| - "Expected #{key} to be <#{value[1]}>, but got <#{value[0]}>." - end.join("\n") - end - - def compare_values(actual) - mismatched_arguments = {} - expected.each do |key, value| - actual_value = actual.send(key) - if actual_value != value - mismatched_arguments[key] = [actual_value, value] - end - end - mismatched_arguments - end - end - - #TODO: Split up tests for each handler into their own files - describe "DefinedTypeHanlder" do - def the_definedtype() - Registry.at("foo::bar") - end - - it "should parse single-line documentation strings before a given defined type" do - comment = "Definition: foo::bar" - puppet_code = <<-PUPPET - # #{comment} - define foo::bar ($baz) { } - PUPPET - - parse(puppet_code, :puppet) - - expect(the_definedtype).to document_a(:type => :definedtype, :docstring => comment) - end - - it "should parse multi-line documentation strings before a given defined type" do - puppet_code = <<-PUPPET - # Definition: foo::bar - # - # This class does some stuff - define foo::bar ($baz) { } - PUPPET - - parse(puppet_code, :puppet) - - comment = "Definition: foo::bar\nThis class does some stuff" - expect(the_definedtype).to document_a(:type => :definedtype, :docstring => comment) - end - - it "should not parse documentation before a function if it is followed by a new line" do - puppet_code = <<-PUPPET - # Definition: foo::bar - - define foo::bar ($baz) { } - PUPPET - - parse(puppet_code, :puppet) - - expect(the_definedtype).to document_a(:type => :definedtype, :docstring => "") - end - it "should not add anything to the Registry if incorrect puppet code is present" do - puppet_code = <<-PUPPET - # Definition: foo::bar - This is not puppet code - PUPPET - - parse(puppet_code, :puppet) - - expect(Registry.all).to be_empty - end - end - - describe "FutureParserDispatchHandler" do - def the_method() - Registry.at("FutureParserFunctions#the_function") - end - - def the_namespace() - Registry.at("FutureParserFunctions") - end - - it "should parse single-line documentation strings before a given function" do - comment = "The summary" - parse <<-RUBY - # #{comment} - Puppet::Functions.create_function(:the_function) do - end - RUBY - - expect(the_method).to document_a(:type => :method, :docstring => comment) - expect(the_namespace).to document_a(:type => :puppetnamespace) - end - - it "should parse multi-line documentation strings before a given function" do - parse <<-RUBY - # The summary - # - # The longer description - Puppet::Functions.create_function(:the_function) do - end - RUBY - - comment = "The summary\n\nThe longer description" - expect(the_method).to document_a(:type => :method, :docstring => comment) - expect(the_namespace).to document_a(:type => :puppetnamespace) - end - - it "should not parse documentation before a function if it is followed by two new lines" do - parse <<-RUBY - # The summary - # - # The longer description - - - Puppet::Functions.create_function(:the_function) do - end - RUBY - - expect(the_method).to document_a(:type => :method, :docstring => "") - expect(the_namespace).to document_a(:type => :puppetnamespace) - end - - it "should not add anything to the Registry if incorrect ruby code is present" do - parse <<-RUBY - # The summary - This is not ruby code - RUBY - - expect(Registry.all).to be_empty - end - end - - describe "ParserFunctionHanlder" do - def the_method() - Registry.at("ParserFunctions#the_function") - end - - def the_namespace() - Registry.at("ParserFunctions") - end - - it "should parse single-line documentation strings before a given function" do - comment = "The summary" - parse <<-RUBY - # #{comment} - newfunction(:the_function, :type => rvalue) do |args| - end - RUBY - - expect(the_method).to document_a(:type => :method, :docstring => comment) - expect(the_namespace).to document_a(:type => :puppetnamespace) - end - - it "should parse multi-line documentation strings before a given function" do - parse <<-RUBY - # The summary - # - # The longer description - newfunction(:the_function, :type => rvalue) do |args| - end - RUBY - - comment = "The summary\n\nThe longer description" - expect(the_method).to document_a(:type => :method, :docstring => comment) - expect(the_namespace).to document_a(:type => :puppetnamespace) - end - - it "should not parse documentation before a function if it is followed by two new lines" do - parse <<-RUBY - # The summary - - - newfunction(:the_function, :type => rvalue) do |args| - end - RUBY - - expect(the_method).to document_a(:type => :method, :docstring => "") - expect(the_namespace).to document_a(:type => :puppetnamespace) - end - end - - describe "HostClassDefintion" do - def the_hostclass() - Registry.at("foo::bar") - end - - it "should parse single-line documentation strings before a given class" do - comment = "Class: foo::bar" - puppet_code = <<-PUPPET - # #{comment} - class foo::bar { } - PUPPET - - parse(puppet_code, :puppet) - - expect(the_hostclass).to document_a(:type => :hostclass, :docstring => comment) - end - - it "should parse multi-line documentation strings before a given class" do - puppet_code = <<-PUPPET - # Class: foo::bar - # - # This class does some stuff - class foo::bar { } - PUPPET - - parse(puppet_code, :puppet) - - comment = "Class: foo::bar\nThis class does some stuff" - expect(the_hostclass).to document_a(:type => :hostclass, :docstring => comment) - end - - it "should not parse documentation before a class if it is followed by a new line" do - puppet_code = <<-PUPPET - # Class: foo::bar - - class foo::bar { } - PUPPET - - parse(puppet_code, :puppet) - - expect(the_hostclass).to document_a(:type => :hostclass, :docstring => "") - end - end -end diff --git a/spec/unit/puppetx/yardoc/yard/host_class_handler_spec.rb b/spec/unit/puppetx/yardoc/yard/host_class_handler_spec.rb new file mode 100644 index 0000000..e594373 --- /dev/null +++ b/spec/unit/puppetx/yardoc/yard/host_class_handler_spec.rb @@ -0,0 +1,49 @@ +require 'spec_helper' +require 'puppetx/yardoc/yard/handlers/host_class_handler' +require 'strings_spec/parsing' + +describe "HostClassDefintion" do + include StringsSpec::Parsing + + def the_hostclass() + Registry.at("foo::bar") + end + + it "should parse single-line documentation strings before a given class" do + comment = "Class: foo::bar" + puppet_code = <<-PUPPET + # #{comment} + class foo::bar { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_hostclass).to document_a(:type => :hostclass, :docstring => comment) + end + + it "should parse multi-line documentation strings before a given class" do + puppet_code = <<-PUPPET + # Class: foo::bar + # + # This class does some stuff + class foo::bar { } + PUPPET + + parse(puppet_code, :puppet) + + comment = "Class: foo::bar\nThis class does some stuff" + expect(the_hostclass).to document_a(:type => :hostclass, :docstring => comment) + end + + it "should not parse documentation before a class if it is followed by a new line" do + puppet_code = <<-PUPPET + # Class: foo::bar + + class foo::bar { } + PUPPET + + parse(puppet_code, :puppet) + + expect(the_hostclass).to document_a(:type => :hostclass, :docstring => "") + end +end diff --git a/spec/unit/puppetx/yardoc/yard/parser_function_handler_spec.rb b/spec/unit/puppetx/yardoc/yard/parser_function_handler_spec.rb new file mode 100644 index 0000000..b84141e --- /dev/null +++ b/spec/unit/puppetx/yardoc/yard/parser_function_handler_spec.rb @@ -0,0 +1,54 @@ +require 'spec_helper' +require 'puppetx/yardoc/yard/handlers/parser_function_handler' +require 'strings_spec/parsing' + +describe "ParserFunctionHanlder" do + include StringsSpec::Parsing + + def the_method() + Registry.at("ParserFunctions#the_function") + end + + def the_namespace() + Registry.at("ParserFunctions") + end + + it "should parse single-line documentation strings before a given function" do + comment = "The summary" + parse <<-RUBY + # #{comment} + newfunction(:the_function, :type => rvalue) do |args| + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should parse multi-line documentation strings before a given function" do + parse <<-RUBY + # The summary + # + # The longer description + newfunction(:the_function, :type => rvalue) do |args| + end + RUBY + + comment = "The summary\n\nThe longer description" + expect(the_method).to document_a(:type => :method, :docstring => comment) + expect(the_namespace).to document_a(:type => :puppetnamespace) + end + + it "should not parse documentation before a function if it is followed by two new lines" do + parse <<-RUBY + # The summary + + + newfunction(:the_function, :type => rvalue) do |args| + end + RUBY + + expect(the_method).to document_a(:type => :method, :docstring => "") + expect(the_namespace).to document_a(:type => :puppetnamespace) + end +end