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.

lib/puppet/parser/functions/dig44.rb

@@ -3,9 +3,7 @@
 # Test whether a given class or definition is defined
 require 'puppet/parser/functions'
 
-Puppet::Parser::Functions.newfunction(:ensure_resource,
-                                      type: :statement,
-                                      doc: <<-DOC,
+Puppet::Parser::Functions.newfunction(:ensure_resource, type: :statement, doc: <<-DOC
   @summary
     Takes a resource type, title, and a list of attributes that describe a
     resource.
@@ -33,7 +31,7 @@
       ensure_resource('user', ['dan','alex'], {'ensure' => 'present'})
 
 DOC
-                                     ) do |vals|
+) do |vals|
   type, title, params = vals
   raise(ArgumentError, 'Must specify a type') unless type
   raise(ArgumentError, 'Must specify a title') unless title

lib/puppet/parser/functions/ensure_resource.rb

@@ -2,9 +2,7 @@
 
 require 'puppet/parser/functions'
 
-Puppet::Parser::Functions.newfunction(:ensure_resources,
-                                      type: :statement,
-                                      doc: <<-DOC,
+Puppet::Parser::Functions.newfunction(:ensure_resources, type: :statement, doc: <<-DOC
   @summary
     Takes a resource type, title (only hash), and a list of attributes that describe a
     resource.
@@ -36,7 +34,7 @@
     Call:
     ensure_resources('user', hiera_hash('userlist'), {'ensure' => 'present'})
 DOC
-                                     ) do |vals|
+) do |vals|
   type, title, params = vals
   raise(ArgumentError, 'Must specify a type') unless type
   raise(ArgumentError, 'Must specify a title') unless title

lib/puppet/parser/functions/ensure_resources.rb

@@ -1,10 +1,6 @@
 # frozen_string_literal: true
 
-Puppet::Parser::Functions.newfunction(
-  :fqdn_rand_string,
-  arity: -2,
-  type: :rvalue,
-  doc: <<-DOC,
+Puppet::Parser::Functions.newfunction(:fqdn_rand_string, arity: -2, type: :rvalue, doc: <<-DOC
   @summary
     Generates a random alphanumeric string. Combining the `$fqdn` fact and an
     optional seed for repeatable randomness.

lib/puppet/parser/functions/fqdn_rand_string.rb

@@ -3,10 +3,7 @@
 #
 # fqdn_rotate.rb
 #
-Puppet::Parser::Functions.newfunction(
-  :fqdn_rotate,
-  type: :rvalue,
-  doc: <<-DOC,
+Puppet::Parser::Functions.newfunction(:fqdn_rotate, type: :rvalue, doc: <<-DOC
   @summary
     Rotates an array or string a random number of times, combining the `$fqdn` fact
     and an optional seed for repeatable randomness.

lib/puppet/parser/functions/fqdn_rotate.rb

@@ -3,9 +3,7 @@
 # Test whether a given class or definition is defined
 require 'puppet/parser/functions'
 
-Puppet::Parser::Functions.newfunction(:getparam,
-                                      type: :rvalue,
-                                      doc: <<-'DOC',
+Puppet::Parser::Functions.newfunction(:getparam, type: :rvalue, doc: <<-'DOC'
     @summary
       Returns the value of a resource's parameter.
 
@@ -45,7 +43,7 @@
       ```Example_resource['example_resource_instance']['param']``
 
   DOC
-                                     ) do |vals|
+) do |vals|
   reference, param = vals
   raise(ArgumentError, 'Must specify a reference') unless reference
   raise(ArgumentError, 'Must specify name of a parameter') unless param&.instance_of?(String)

lib/puppet/parser/functions/getparam.rb

@@ -6,9 +6,11 @@
 module Puppet::Parser::Functions
   newfunction(:pick, type: :rvalue, doc: <<-EOS
     @summary
-      This function is similar to a coalesce function in SQL in that it will return
+      This function will return
       the first value in a list of values that is not undefined or an empty string.
 
+    This function is similar to a coalesce function in SQL.
+
     @return
       the first value in a list of values that is not undefined or an empty string.
 

lib/puppet/parser/functions/pick.rb

@@ -3,11 +3,7 @@
 #  Please note: This function is an implementation of a Ruby class and as such may not be entirely UTF8 compatible.
 #  To ensure compatibility please use this function with Ruby 2.4.0 or greater - https://bugs.ruby-lang.org/issues/10085.
 #
-Puppet::Parser::Functions.newfunction(
-  :pw_hash,
-  type: :rvalue,
-  arity: 3,
-  doc: <<-DOC,
+Puppet::Parser::Functions.newfunction(:pw_hash, type: :rvalue, arity: 3, doc: <<-DOC
   @summary
     Hashes a password using the crypt function. Provides a hash usable
     on most POSIX systems.

lib/puppet/parser/functions/pw_hash.rb

@@ -11,11 +11,9 @@ module Puppet::Parser::Functions
     @return
       the rounded value as integer
 
-    @example
-
-    ```round(2.9)``` returns ```3```
-
-    ```round(2.4)``` returns ```2```
+    @example Example usage
+        round(2.9) #=> 3
+        round(2.4) #=> 2
 
     > *Note:* from Puppet 6.0.0, the compatible function with the same name in Puppet core
       will be used instead of this function.

lib/puppet/parser/functions/round.rb

@@ -3,11 +3,7 @@
 #
 # seeded_rand.rb
 #
-Puppet::Parser::Functions.newfunction(
-  :seeded_rand,
-  arity: 2,
-  type: :rvalue,
-  doc: <<-DOC,
+Puppet::Parser::Functions.newfunction(:seeded_rand, arity: 2, type: :rvalue, doc: <<-DOC
     @summary
       Generates a random whole number greater than or equal to 0 and less than MAX, using the value of SEED for repeatable randomness.
 

lib/puppet/parser/functions/seeded_rand.rb

@@ -4,11 +4,7 @@
 # try_get_value.rb
 #
 module Puppet::Parser::Functions
-  newfunction(
-    :try_get_value,
-    type: :rvalue,
-    arity: -2,
-    doc: <<-DOC,
+  newfunction(:try_get_value, type: :rvalue, arity: -2, doc: <<-DOC
       @summary
         **DEPRECATED:** this function is deprecated, please use dig() instead.
 

lib/puppet/parser/functions/try_get_value.rb

@@ -7,8 +7,9 @@ module Puppet::Parser::Functions
   newfunction(:validate_slength, doc: <<-DOC
     @summary
       Validate that the first argument is a string (or an array of strings), and less/equal to than the length of the second argument.
-      An optional third parameter can be given the minimum length. It fails if the first argument is not a string or array of strings,
-      and if arg 2 and arg 3 are not convertable to a number.
+
+    An optional third parameter can be given the minimum length. It fails if the first argument is not a string or array of strings,
+    and if arg 2 and arg 3 are not convertable to a number.
 
     @return
       validate that the first argument is a string (or an array of strings), and less/equal to than the length of the second argument. Fail compilation if any of the checks fail.

lib/puppet/parser/functions/validate_slength.rb

@@ -7,8 +7,10 @@ module Puppet::Parser::Functions
   newfunction(:validate_x509_rsa_key_pair, doc: <<-DOC
     @summary
       Validates a PEM-formatted X.509 certificate and RSA private key using
-      OpenSSL. Verifies that the certficate's signature was created from the
-      supplied key.
+      OpenSSL.
+
+    Verifies that the certficate's signature was created from the
+    supplied key.
 
     @return
       Fail compilation if any value fails this check.

lib/puppet/parser/functions/validate_x509_rsa_key_pair.rb

@@ -30,14 +30,14 @@
 #       }
 #
 # @example
-# stdlib::manage::create_resources:
-#   file:
-#     '/etc/motd.d/hello':
-#       content: I say Hi
-#       notify: 'Service[sshd]'
-#   package:
-#     example:
-#       ensure: installed
+#   stdlib::manage::create_resources:
+#     file:
+#       '/etc/motd.d/hello':
+#         content: I say Hi
+#         notify: 'Service[sshd]'
+#     package:
+#       example:
+#         ensure: installed
 class stdlib::manage (
   Hash[String, Hash] $create_resources = {}
 ) {

manifests/manage.pp

@@ -1,2 +1,2 @@
-# A strict absolutepath type
+# @summary A strict absolutepath type
 type Stdlib::Absolutepath = Variant[Stdlib::Windowspath, Stdlib::Unixpath]

types/absolutepath.pp

@@ -1,2 +1,2 @@
-# Type to match base32 String
+# @summary Type to match base32 String
 type Stdlib::Base32 = Pattern[/\A[a-z2-7]+={,6}\z/, /\A[A-Z2-7]+={,6}\z/]

types/base32.pp

@@ -1,2 +1,2 @@
-# Type to match base64 String
+# @summary Type to match base64 String
 type Stdlib::Base64 = Pattern[/\A[a-zA-Z0-9\/\+]+={,2}\z/]

types/base64.pp

@@ -1,4 +1,4 @@
-# Emulate the is_absolute_path and validate_absolute_path functions
+# @summary Emulate the is_absolute_path and validate_absolute_path functions
 #
 # The first pattern is originally from is_absolute_path, which had it from 2.7.x's lib/puppet/util.rb Puppet::Util.absolute_path?
 # slash = '[\\\\/]'

types/compat/absolute_path.pp

@@ -1,2 +1,2 @@
-# Emulate the is_array and validate_array functions
+# @summary Emulate the is_array and validate_array functions
 type Stdlib::Compat::Array = Array[Any]