puppet-strings 0.99.0 → 1.0.0

data/spec/fixtures/unit/json/output_without_puppet_function.json

@@ -84,7 +84,7 @@
     {
       "name": "database",
       "file": "(stdin)",
-      "line": 43,
+      "line": 54,
       "docstring": {
         "text": "An example database server resource type."
       },
@@ -154,7 +154,7 @@
       "name": "linux",
       "type_name": "database",
       "file": "(stdin)",
-      "line": 33,
+      "line": 43,
       "docstring": {
         "text": "An example provider on Linux."
       },
@@ -166,9 +166,24 @@
         "implements_some_feature",
         "some_other_feature"
       ],
-      "defaults": {
-        "kernel": "Linux"
-      },
+      "defaults": [
+        [
+          [
+            "kernel",
+            "Linux"
+          ]
+        ],
+        [
+          [
+            "osfamily",
+            "RedHat"
+          ],
+          [
+            "operatingsystemmajrelease",
+            "7"
+          ]
+        ]
+      ],
       "commands": {
         "foo": "/usr/bin/foo"
       }
@@ -180,7 +195,39 @@
       "file": "(stdin)",
       "line": 1,
       "type": "ruby3x",
-      "signature": "func3x(String $first, Any $second)",
+      "signatures": [
+        {
+          "signature": "func3x(String $first, Any $second)",
+          "docstring": {
+            "text": "An example 3.x function.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "String"
+                ],
+                "name": "first"
+              },
+              {
+                "tag_name": "param",
+                "text": "The second parameter.",
+                "types": [
+                  "Any"
+                ],
+                "name": "second"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns nothing.",
+                "types": [
+                  "Undef"
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "docstring": {
         "text": "An example 3.x function.",
         "tags": [
@@ -216,6 +263,78 @@
       "file": "(stdin)",
       "line": 11,
       "type": "ruby4x",
+      "signatures": [
+        {
+          "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
+          "docstring": {
+            "text": "The first overload.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "Integer"
+                ],
+                "name": "param1"
+              },
+              {
+                "tag_name": "param",
+                "text": "The second parameter.",
+                "types": [
+                  "Any"
+                ],
+                "name": "param2"
+              },
+              {
+                "tag_name": "param",
+                "text": "The third parameter.",
+                "types": [
+                  "Optional[Array[String]]"
+                ],
+                "name": "param3"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns nothing.",
+                "types": [
+                  "Undef"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "signature": "func4x(Boolean $param, Callable &$block)",
+          "docstring": {
+            "text": "",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "Boolean"
+                ],
+                "name": "param"
+              },
+              {
+                "tag_name": "param",
+                "text": "The block parameter.",
+                "types": [
+                  "Callable"
+                ],
+                "name": "&block"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns a string.",
+                "types": [
+                  "String"
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "docstring": {
         "text": "An example 4.x function.",
         "tags": [
@@ -264,7 +383,7 @@
             "tag_name": "overload",
             "signature": "func4x(Boolean $param, Callable &$block)",
             "docstring": {
-              "text": "The second overload.",
+              "text": "",
               "tags": [
                 {
                   "tag_name": "param",
@@ -295,7 +414,59 @@
           }
         ]
       },
-      "source": "Puppet::Functions.create_function(:func4x) do\n  # The first overload.\n  # @param param1 The first parameter.\n  # @param param2 The second parameter.\n  # @param param3 The third parameter.\n  # @return [Undef] Returns nothing.\n  dispatch :foo do\n    param          'Integer',       :param1\n    param          'Any',           :param2\n    optional_param 'Array[String]', :param3\n  end\n\n  # The second overload.\n  # @param param The first parameter.\n  # @param block The block parameter.\n  # @return [String] Returns a string.\n  dispatch :other do\n    param 'Boolean', :param\n    block_param\n  end\nend"
+      "source": "Puppet::Functions.create_function(:func4x) do\n  # The first overload.\n  # @param param1 The first parameter.\n  # @param param2 The second parameter.\n  # @param param3 The third parameter.\n  # @return Returns nothing.\n  dispatch :foo do\n    param          'Integer',       :param1\n    param          'Any',           :param2\n    optional_param 'Array[String]', :param3\n    return_type 'Undef'\n  end\n\n  # @param param The first parameter.\n  # @param block The block parameter.\n  # @return Returns a string.\n  dispatch :other do\n    param 'Boolean', :param\n    block_param\n    return_type 'String'\n  end\nend"
+    },
+    {
+      "name": "func4x_1",
+      "file": "(stdin)",
+      "line": 35,
+      "type": "ruby4x",
+      "signatures": [
+        {
+          "signature": "func4x_1(Integer $param1)",
+          "docstring": {
+            "text": "An example 4.x function with only one signature.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "Integer"
+                ],
+                "name": "param1"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns nothing.",
+                "types": [
+                  "Undef"
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "docstring": {
+        "text": "An example 4.x function with only one signature.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "The first parameter.",
+            "types": [
+              "Integer"
+            ],
+            "name": "param1"
+          },
+          {
+            "tag_name": "return",
+            "text": "Returns nothing.",
+            "types": [
+              "Undef"
+            ]
+          }
+        ]
+      },
+      "source": "Puppet::Functions.create_function(:func4x_1) do\n  # @param param1 The first parameter.\n  # @return [Undef] Returns nothing.\n  dispatch :foobarbaz do\n    param          'Integer',       :param1\n  end\nend"
     }
   ]
 }

data/spec/spec_helper.rb

@@ -10,6 +10,9 @@ PuppetStrings::Yard.setup!
 # Enable testing of Puppet functions if running against 4.1+
 TEST_PUPPET_FUNCTIONS = Gem::Dependency.new('', '>= 4.1.0').match?('', Puppet::PUPPETVERSION)
 
+# Enable testing of Puppet language functions declared with return type if running against 4.8+
+TEST_FUNCTION_RETURN_TYPE = Gem::Dependency.new('', '>= 4.8.0').match?('', Puppet::PUPPETVERSION)
+
 RSpec.configure do |config|
   config.mock_with :mocha
 

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

@@ -48,20 +48,30 @@ Puppet::Functions.create_function(:func4x) do
   # @param param1 The first parameter.
   # @param param2 The second parameter.
   # @param param3 The third parameter.
-  # @return [Undef] Returns nothing.
+  # @return Returns nothing.
   dispatch :foo do
     param          'Integer',       :param1
     param          'Any',           :param2
     optional_param 'Array[String]', :param3
+    return_type 'Undef'
   end
 
-  # The second overload.
   # @param param The first parameter.
   # @param block The block parameter.
-  # @return [String] Returns a string.
+  # @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
 
@@ -69,7 +79,8 @@ Puppet::Type.type(:database).provide :linux do
   desc 'An example provider on Linux.'
   confine kernel: 'Linux'
   confine osfamily: 'RedHat'
-  defaultfor kernel: 'Linux'
+  defaultfor :kernel => 'Linux'
+  defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7'
   has_feature :implements_some_feature
   has_feature :some_other_feature
   commands foo: /usr/bin/foo

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

@@ -68,6 +68,11 @@ SOURCE
       expect(tags[2].name).to eq('param3')
       expect(tags[2].text).to eq('Third param.')
       expect(tags[2].types).to eq(['String'])
+      tags = object.docstring.tags(:return)
+      expect(tags.size).to eq(1)
+      expect(tags[0].tag_name).to eq('return')
+      expect(tags[0].text).to eq('Returns nothing.')
+      expect(tags[0].types).to eq(['Undef'])
       tags = object.docstring.tags(:api)
       expect(tags.size).to eq(1)
       expect(tags[0].text).to eq('public')
@@ -166,4 +171,71 @@ SOURCE
       expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):5\./).to_stdout_from_any_process
     end
   end
+
+  describe 'parsing a function with a missing @return tag and return type specified in the function definition', if: TEST_FUNCTION_RETURN_TYPE do
+    let(:source) { <<-SOURCE
+# A simple foo function.
+function foo() >> String {
+  notice 'hello world'
+}
+SOURCE
+    }
+
+    it 'should register a function object with the correct return type' do
+      expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
+      tags = object.docstring.tags(:return)
+      expect(tags.size).to eq(1)
+      expect(tags[0].tag_name).to eq('return')
+      expect(tags[0].text).to eq('')
+      expect(tags[0].types).to eq(['String'])
+    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.
+# @return [Integer] this is a lie.
+function foo() >> Struct[{'a' => Integer[1, 10]}] {
+  notice 'hello world'
+}
+SOURCE
+    }
+
+    it 'should prefer the return type from the function definition' do
+      expect{ subject }.to output(/\[warn\]: Documented return type does not match return type in function definition near \(stdin\):3\./).to_stdout_from_any_process
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
+      tags = object.docstring.tags(:return)
+      expect(tags.size).to eq(1)
+      expect(tags[0].tag_name).to eq('return')
+      expect(tags[0].text).to eq('this is a lie.')
+      expect(tags[0].types).to eq(["Struct[{'a' => Integer[1, 10]}]"])
+    end
+  end
+
+  describe 'parsing a function without a return tag or return type in the function definition' do
+    let(:source) { <<-SOURCE
+# A simple foo function.
+function foo() {
+  notice 'hello world'
+}
+SOURCE
+    }
+
+    it 'should add a return tag with a default type value of Any' do
+      expect{ subject }.to output(/\[warn\]: Missing @return tag near \(stdin\):2\./).to_stdout_from_any_process
+      expect(subject.size).to eq(1)
+      object = subject.first
+      expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
+      tags = object.docstring.tags(:return)
+      expect(tags.size).to eq(1)
+      expect(tags[0].tag_name).to eq('return')
+      expect(tags[0].text).to eq('')
+      expect(tags[0].types).to eq(['Any'])
+    end
+  end
 end

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

@@ -70,6 +70,50 @@ SOURCE
       end
     end
 
+    describe 'parsing a function with a doc parameter which has a newline between the namespace and the newfunction call' do
+      let(:source) { <<-SOURCE
+module Puppet::Parser::Functions
+  newfunction(:foo, doc: <<-DOC
+An example 3.x function.
+@param [String] first The first parameter.
+@param second The second parameter.
+@return [Undef] Returns nothing.
+DOC
+) do |*args|
+  end
+end
+SOURCE
+      }
+
+      it 'should register a function object' do
+        expect(subject.size).to eq(1)
+        object = subject.first
+        expect(object).to be_a(PuppetStrings::Yard::CodeObjects::Function)
+        expect(object.namespace).to eq(PuppetStrings::Yard::CodeObjects::Functions.instance(PuppetStrings::Yard::CodeObjects::Function::RUBY_3X))
+        expect(object.name).to eq(:foo)
+        expect(object.signature).to eq('foo(String $first, Any $second)')
+        expect(object.parameters).to eq([['first', nil], ['second', nil]])
+        expect(object.docstring).to eq('An example 3.x function.')
+        expect(object.docstring.tags.size).to eq(4)
+        tags = object.docstring.tags(:param)
+        expect(tags.size).to eq(2)
+        expect(tags[0].name).to eq('first')
+        expect(tags[0].text).to eq('The first parameter.')
+        expect(tags[0].types).to eq(['String'])
+        expect(tags[1].name).to eq('second')
+        expect(tags[1].text).to eq('The second parameter.')
+        expect(tags[1].types).to eq(['Any'])
+        tags = object.docstring.tags(:return)
+        expect(tags.size).to eq(1)
+        expect(tags[0].name).to be_nil
+        expect(tags[0].text).to eq('Returns nothing.')
+        expect(tags[0].types).to eq(['Undef'])
+        tags = object.docstring.tags(:api)
+        expect(tags.size).to eq(1)
+        expect(tags[0].text).to eq('public')
+      end
+    end
+
     describe 'parsing a function with a missing @return tag' do
       let(:source) { <<-SOURCE
 Puppet::Parser::Functions.newfunction(:foo, doc: <<-DOC) do |*args|

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

@@ -55,13 +55,31 @@ 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
   desc 'An example provider on Linux.'
   confine kernel: 'Linux'
   confine osfamily: 'RedHat'
-  defaultfor kernel: 'Linux'
+  defaultfor :kernel => 'Linux'
+  defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7'
   has_feature :implements_some_feature
   has_feature :some_other_feature
   commands foo: /usr/bin/foo
@@ -82,7 +100,7 @@ SOURCE
       expect(tags.size).to eq(1)
       expect(tags[0].text).to eq('public')
       expect(object.confines).to eq({ 'kernel' => 'Linux', 'osfamily' => 'RedHat'})
-      expect(object.defaults).to eq({ 'kernel' => 'Linux'})
+      expect(object.defaults).to eq([[["kernel", "Linux"]], [["osfamily", "RedHat"], ["operatingsystemmajrelease", "7"]]])
       expect(object.features).to eq(['implements_some_feature', 'some_other_feature'])
       expect(object.commands).to eq({'foo' => '/usr/bin/foo'})
     end