Merge pull request #118 from whopper/PDOC-126/master/ruby_quotes

(PDOC-126) Remove `%Q` ruby quotation syntax from parsed strings

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.

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
 

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

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}."

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

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

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.

spec/unit/puppet-strings/yard/util_spec.rb

@@ -0,0 +1,31 @@
+require 'spec_helper'
+require 'puppet-strings/yard'
+
+describe PuppetStrings::Yard::Util do
+  subject {PuppetStrings::Yard::Util}
+
+  describe 'scrub_string' do
+    it 'should remove `%Q` and its brackets from a string ' do
+      str = "%Q{this is a test string}"
+      expect(subject.scrub_string(str)).to eq('this is a test string')
+    end
+
+    it 'should remove `%q` and its brackets from a string' do
+      str = "%q{this is a test string}"
+      expect(subject.scrub_string(str)).to eq('this is a test string')
+    end
+
+    it 'should not affect newlines when %Q notation is used' do
+      str = <<-STR
+%Q{this is
+a test string}
+STR
+      expect(subject.scrub_string(str)).to eq("this is\na test string")
+    end
+
+    it 'should not affect a string which does not use %Q notation' do
+      str = "this is a test string"
+      expect(subject.scrub_string(str)).to eq('this is a test string')
+    end
+  end
+end