Merge pull request #125 from whopper/PDOC-135/4x_dispatch_return_type

(PDOC-135) Detect `return_type` calls in 4.x function dispatches

lib/puppet-strings/yard/handlers/ruby/function_handler.rb

@@ -15,6 +15,7 @@ class PuppetStrings::Yard::Handlers::Ruby::FunctionHandler < PuppetStrings::Yard
     block_param
     required_block_param
     optional_block_param
+    return_type
   ).freeze
 
   namespace_only
@@ -133,6 +134,11 @@ def add_overload_tag(object, node)
       method_name = child.method_name.source
       next unless DISPATCH_METHOD_NAMES.include?(method_name)
 
+      if method_name == 'return_type'
+        overload_tag.tag(:return).types = [node_as_string(child.parameters[0])]
+        next
+      end
+
       # Check for block
       if method_name.include?('block')
         if block

spec/fixtures/unit/json/output.json

@@ -84,7 +84,7 @@
     {
       "name": "database",
       "file": "(stdin)",
-      "line": 44,
+      "line": 46,
       "docstring": {
         "text": "An example database server resource type."
       },
@@ -154,7 +154,7 @@
       "name": "linux",
       "type_name": "database",
       "file": "(stdin)",
-      "line": 33,
+      "line": 35,
       "docstring": {
         "text": "An example provider on Linux."
       },
@@ -357,7 +357,7 @@
           }
         ]
       },
-      "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  # The second overload.\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"
     }
   ]
 }

spec/fixtures/unit/json/output_without_puppet_function.json

@@ -84,7 +84,7 @@
     {
       "name": "database",
       "file": "(stdin)",
-      "line": 44,
+      "line": 46,
       "docstring": {
         "text": "An example database server resource type."
       },
@@ -154,7 +154,7 @@
       "name": "linux",
       "type_name": "database",
       "file": "(stdin)",
-      "line": 33,
+      "line": 35,
       "docstring": {
         "text": "An example provider on Linux."
       },
@@ -310,7 +310,7 @@
           }
         ]
       },
-      "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  # The second overload.\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"
     }
   ]
 }

spec/unit/puppet-strings/json_spec.rb

@@ -48,20 +48,22 @@ class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {
   # @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