Merge pull request #1239 from puppetlabs/unbreak-rake-reference

Unbreak `rake strings:generate:reference`

Author: david22swan

REFERENCE.md

@@ -1,4 +1,6 @@
 # @summary function to cast ensure parameter to resource specific value
+#
+# @return [String]
 function stdlib::ensure(
   Variant[Boolean, Enum['present', 'absent']] $ensure,
   Enum['directory', 'link', 'mounted', 'service', 'file', 'package'] $resource,

functions/ensure.pp

@@ -4,15 +4,13 @@
 #   This function accepts HOCON as a string and converts it into the correct
 #   Puppet structure
 #
-# @return
-#   Data
-#
 # @example How to parse hocon
 #   $data = parsehocon("{any valid hocon: string}")
 #
 Puppet::Functions.create_function(:parsehocon) do
   # @param hocon_string A valid HOCON string
   # @param default An optional default to return if parsing hocon_string fails
+  # @return [Data]
   dispatch :parsehocon do
     param          'String', :hocon_string
     optional_param 'Any',    :default

lib/puppet/functions/parsehocon.rb

@@ -3,15 +3,15 @@
 # @summary
 #   This converts a string to a puppet resource.
 #
-#   This attempts to convert a string like 'File[/foo]' into the
-#   puppet resource `File['/foo']` as detected by the catalog.
+# This attempts to convert a string like 'File[/foo]' into the
+# puppet resource `File['/foo']` as detected by the catalog.
 #
-#   Things like 'File[/foo, /bar]' are not supported as a
-#   title might contain things like ',' or ' '.  There is
-#   no clear value seperator to use.
+# Things like 'File[/foo, /bar]' are not supported as a
+# title might contain things like ',' or ' '.  There is
+# no clear value seperator to use.
 #
-#   This function can depend on the parse order of your
-#   manifests/modules as it inspects the catalog thus far.
+# This function can depend on the parse order of your
+# manifests/modules as it inspects the catalog thus far.
 Puppet::Functions.create_function(:'stdlib::str2resource') do
   # @param res_string The string to lookup as a resource
   # @example

lib/puppet/functions/stdlib/str2resource.rb

@@ -3,16 +3,16 @@
 require 'json'
 # @summary
 #   Convert a data structure and output to JSON
-#
-# @example Output JSON to a file
-#   file { '/tmp/my.json':
-#     ensure  => file,
-#     content => to_json($myhash),
-#   }
-#
 Puppet::Functions.create_function(:to_json) do
   # @param data
   #   Data structure which needs to be converted into JSON
+  #
+  # @example Output JSON to a file
+  #   file { '/tmp/my.json':
+  #     ensure  => file,
+  #     content => to_json($myhash),
+  #   }
+  #
   # @return [String] Converted data to JSON
   dispatch :to_json do
     param 'Any', :data

lib/puppet/functions/to_json.rb

@@ -15,15 +15,15 @@
 #   }
 
 Puppet::Functions.create_function(:to_python) do
-  dispatch :to_python do
-    param 'Any', :object
-  end
-
   # @param object
   #   The object to be converted
   #
   # @return [String]
   #   The String representation of the object
+  dispatch :to_python do
+    param 'Any', :object
+  end
+
   def to_python(object)
     serialized = Puppet::Pops::Serialization::ToDataConverter.convert(object, rich_data: true)
     serialized_to_python(serialized)

lib/puppet/functions/to_python.rb

@@ -15,15 +15,15 @@
 #   }
 
 Puppet::Functions.create_function(:to_ruby) do
-  dispatch :to_ruby do
-    param 'Any', :object
-  end
-
   # @param object
   #   The object to be converted
   #
   # @return [String]
   #   The String representation of the object
+  dispatch :to_ruby do
+    param 'Any', :object
+  end
+
   def to_ruby(object)
     serialized = Puppet::Pops::Serialization::ToDataConverter.convert(object, rich_data: true)
     serialized_to_ruby(serialized)

lib/puppet/functions/to_ruby.rb

@@ -3,23 +3,23 @@
 require 'yaml'
 # @summary
 #   Convert a data structure and output it as YAML
-#
-# @example Output YAML to a file
-#   file { '/tmp/my.yaml':
-#     ensure  => file,
-#     content => to_yaml($myhash),
-#   }
-# @example Use options to control the output format
-#   file { '/tmp/my.yaml':
-#     ensure  => file,
-#     content => to_yaml($myhash, {indentation => 4})
-#   }
 Puppet::Functions.create_function(:to_yaml) do
   # @param data
   #   The data you want to convert to YAML
   # @param options
   #   A hash of options that will be passed to Ruby's Psych library. Note, this could change between Puppet versions, but at time of writing these are `line_width`, `indentation`, and `canonical`.
   #
+  # @example Output YAML to a file
+  #   file { '/tmp/my.yaml':
+  #     ensure  => file,
+  #     content => to_yaml($myhash),
+  #   }
+  # @example Use options to control the output format
+  #   file { '/tmp/my.yaml':
+  #     ensure  => file,
+  #     content => to_yaml($myhash, {indentation => 4})
+  #   }
+  #
   # @return [String] The YAML document
   dispatch :to_yaml do
     param 'Any', :data

lib/puppet/functions/to_yaml.rb

@@ -3,9 +3,7 @@
 # Test whether a given class or definition is defined
 require 'puppet/parser/functions'
 
-Puppet::Parser::Functions.newfunction(:defined_with_params,
-                                      type: :rvalue,
-                                      doc: <<-DOC,
+Puppet::Parser::Functions.newfunction(:defined_with_params, type: :rvalue, doc: <<-DOC
     @summary
       Takes a resource reference and an optional hash of attributes.
 
@@ -25,7 +23,7 @@
     @return [Boolean]
       returns `true` or `false`
 DOC
-                                     ) do |vals|
+) do |vals|
   reference, params = vals
   raise(ArgumentError, 'Must specify a reference') unless reference
   if !params || params == ''

lib/puppet/parser/functions/defined_with_params.rb

@@ -4,11 +4,7 @@
 # dig44.rb
 #
 module Puppet::Parser::Functions
-  newfunction(
-    :dig44,
-    type: :rvalue,
-    arity: -2,
-    doc: <<-DOC,
+  newfunction(:dig44, type: :rvalue, arity: -2, doc: <<-DOC
     @summary
       **DEPRECATED**: Looks up into a complex structure of arrays and hashes and returns a value
       or the default value if nothing was found.