diff --git a/lib/puppet-strings/yard/code_objects/type.rb b/lib/puppet-strings/yard/code_objects/type.rb index 8bb1983..fe0a4b6 100644 --- a/lib/puppet-strings/yard/code_objects/type.rb +++ b/lib/puppet-strings/yard/code_objects/type.rb @@ -1,4 +1,5 @@ require 'puppet-strings/yard/code_objects/group' +require 'puppet-strings/yard/util' # Implements the group for Puppet resource types. class PuppetStrings::Yard::CodeObjects::Types < PuppetStrings::Yard::CodeObjects::Group @@ -78,7 +79,7 @@ class PuppetStrings::Yard::CodeObjects::Type < PuppetStrings::Yard::CodeObjects: # @param [String] docstring The docstring of the feature. def initialize(name, docstring) @name = name - @docstring = Puppet::Util::Docs.scrub(docstring).gsub("\n", ' ') + @docstring = PuppetStrings::Yard::Util.scrub_string(docstring).gsub("\n", ' ') end # Converts the feature to a hash representation. diff --git a/lib/puppet-strings/yard/handlers/ruby/function_handler.rb b/lib/puppet-strings/yard/handlers/ruby/function_handler.rb index e515b5a..6f1fc3e 100644 --- a/lib/puppet-strings/yard/handlers/ruby/function_handler.rb +++ b/lib/puppet-strings/yard/handlers/ruby/function_handler.rb @@ -1,6 +1,6 @@ require 'puppet-strings/yard/handlers/ruby/base' require 'puppet-strings/yard/code_objects' -require 'puppet/util/docs' +require 'puppet-strings/yard/util' # Implements the handler for Puppet functions written in Ruby. class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard::Handlers::Ruby::Base @@ -338,7 +338,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard docstring = node_as_string(kvp[1]) log.error "Failed to parse docstring for 3.x Puppet function '#{name}' near #{statement.file}:#{statement.line}." and return nil unless docstring - return Puppet::Util::Docs.scrub(docstring) + return PuppetStrings::Yard::Util.scrub_string(docstring) end end diff --git a/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb b/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb index 91abc6e..f3141be 100644 --- a/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb +++ b/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb @@ -1,6 +1,6 @@ require 'puppet-strings/yard/handlers/ruby/base' require 'puppet-strings/yard/code_objects' -require 'puppet/util/docs' +require 'puppet-strings/yard/util' # Implements the handler for Puppet providers written in Ruby. class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard::Handlers::Ruby::Base @@ -53,7 +53,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard next unless ivar != child && ivar.source == '@doc' docstring = node_as_string(child[1]) log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring - register_docstring(object, Puppet::Util::Docs.scrub(docstring), nil) + register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil) return nil elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode) # Look for a call to a dispatch method with a block @@ -64,7 +64,7 @@ class PuppetStrings::Yard::Handlers::Ruby::ProviderHandler < PuppetStrings::Yard docstring = node_as_string(child.parameters[0]) log.error "Failed to parse docstring for Puppet provider '#{object.name}' (resource type '#{object.type_name}') near #{child.file}:#{child.line}." and return nil unless docstring - register_docstring(object, Puppet::Util::Docs.scrub(docstring), nil) + register_docstring(object, PuppetStrings::Yard::Util.scrub_string(docstring), nil) return nil end end diff --git a/lib/puppet-strings/yard/handlers/ruby/type_handler.rb b/lib/puppet-strings/yard/handlers/ruby/type_handler.rb index 86ee94e..a616ad5 100644 --- a/lib/puppet-strings/yard/handlers/ruby/type_handler.rb +++ b/lib/puppet-strings/yard/handlers/ruby/type_handler.rb @@ -1,6 +1,6 @@ require 'puppet-strings/yard/handlers/ruby/base' require 'puppet-strings/yard/code_objects' -require 'puppet/util' +require 'puppet-strings/yard/util' # Implements the handler for Puppet resource types written in Ruby. class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Handlers::Ruby::Base @@ -49,7 +49,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha next unless ivar != child && ivar.source == '@doc' docstring = node_as_string(child[1]) log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring - return Puppet::Util::Docs.scrub(docstring) + return PuppetStrings::Yard::Util.scrub_string(docstring) elsif child.is_a?(YARD::Parser::Ruby::MethodCallNode) # Look for a call to a dispatch method with a block next unless child.method_name && @@ -58,7 +58,7 @@ class PuppetStrings::Yard::Handlers::Ruby::TypeHandler < PuppetStrings::Yard::Ha docstring = node_as_string(child.parameters[0]) log.error "Failed to parse docstring for #{kind} near #{child.file}:#{child.line}." and return nil unless docstring - return Puppet::Util::Docs.scrub(docstring) + return PuppetStrings::Yard::Util.scrub_string(docstring) end end log.warn "Missing a description for #{kind} at #{node.file}:#{node.line}." diff --git a/lib/puppet-strings/yard/util.rb b/lib/puppet-strings/yard/util.rb new file mode 100644 index 0000000..809bd55 --- /dev/null +++ b/lib/puppet-strings/yard/util.rb @@ -0,0 +1,17 @@ +require 'puppet/util' + +# The module for various puppet-strings utility helpers. +module PuppetStrings::Yard::Util + # Trims indentation from trailing whitespace and removes ruby literal quotation + # syntax `%Q{}` and `%{q}` from parsed strings. + # @param [String] str The string to scrub. + # @return [String] A scrubbed string. + def self.scrub_string(str) + match = str.match(/^%[Qq]{(.*)}$/m) + if match + return Puppet::Util::Docs.scrub(match[1]) + end + + Puppet::Util::Docs.scrub(str) + end +end 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 3855f26..3f4b23a 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 @@ -55,6 +55,23 @@ SOURCE end end + describe 'parsing a provider with a docstring which uses ruby `%Q` notation' do + 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 + } + + 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 provider definition' do let(:source) { <<-SOURCE Puppet::Type.type(:custom).provide :linux do 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 c3578f1..e66c460 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 @@ -55,6 +55,23 @@ SOURCE end end + describe 'parsing a type with a docstring which uses ruby `%Q` notation' do + 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 + } + + 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.