Add/modify Strings-style documentation

Author: eputnam

lib/puppet/functions/mysql/deepmerge.rb

@@ -1,16 +1,16 @@
-# Recursively merges two or more hashes together and returns the resulting hash.
-#    For example:
+# @summary Recursively merges two or more hashes together and returns the resulting hash.
 #
-#        $hash1 = {'one' => 1, 'two' => 2, 'three' => { 'four' => 4 } }
-#        $hash2 = {'two' => 'dos', 'three' => { 'five' => 5 } }
-#        $merged_hash = mysql::deepmerge($hash1, $hash2)
-#        # The resulting hash is equivalent to:
-#        # $merged_hash = { 'one' => 1, 'two' => 'dos', 'three' => { 'four' => 4, 'five' => 5 } }
+# @example
+#   $hash1 = {'one' => 1, 'two' => 2, 'three' => { 'four' => 4 } }
+#   $hash2 = {'two' => 'dos', 'three' => { 'five' => 5 } }
+#   $merged_hash = mysql_deepmerge($hash1, $hash2)
+#   # The resulting hash is equivalent to:
+#   # $merged_hash = { 'one' => 1, 'two' => 'dos', 'three' => { 'four' => 4, 'five' => 5 } }
+#
+# - When there is a duplicate key that is a hash, they are recursively merged.
+# - When there is a duplicate key that is not a hash, the key in the rightmost hash will "win."
+# - When there are conficting uses of dashes and underscores in two keys (which mysql would otherwise equate), the rightmost style will win.
 #
-#    When there is a duplicate key that is a hash, they are recursively merged.
-#    When there is a duplicate key that is not a hash, the key in the rightmost hash will "win."
-#    When there are conficting uses of dashes and underscores in two keys (which mysql would otherwise equate),
-#      the rightmost style will win.
 Puppet::Functions.create_function(:'mysql::deepmerge') do
   def deepmerge(*args)
     if args.length < 2

lib/puppet/functions/mysql/dirname.rb

@@ -1,5 +1,13 @@
-# Returns the dirname of a path.
+# @summary
+#   Returns the dirname of a path
+#
 Puppet::Functions.create_function(:'mysql::dirname') do
+  # @param path
+  #   Path to find the dirname for.
+  #
+  # @return
+  #   Directory name of path.
+  #
   dispatch :dirname do
     required_param 'Variant[String, Undef]', :path
     return_type 'String'

lib/puppet/functions/mysql/password.rb

@@ -1,7 +1,13 @@
 require 'digest/sha1'
-# Returns the mysql password hash from the clear text password.
-# Hash a string as mysql's "PASSWORD()" function would do it
+# @summary
+#   Hash a string as mysql's "PASSWORD()" function would do it
+#
 Puppet::Functions.create_function(:'mysql::password') do
+  # @param password
+  #   Plain text password.
+  #
+  # @return the mysql password hash from the clear text password.
+  #
   dispatch :password do
     required_param 'String', :password
     return_type 'String'

lib/puppet/functions/mysql/strip_hash.rb

@@ -1,5 +1,10 @@
-# When given a hash this function strips out all blank entries.
+# @summary
+#   When given a hash this function strips out all blank entries.
+#
 Puppet::Functions.create_function(:'mysql::strip_hash') do
+  # @param hash
+  #   Hash to be stripped
+  #
   dispatch :strip_hash do
     required_param 'Hash', :hash
     return_type 'Hash'

lib/puppet/parser/functions/mysql_deepmerge.rb

@@ -1,25 +1,22 @@
-# Recursively merges two or more hashes together and returns the resulting hash.
 module Puppet::Parser::Functions
   newfunction(:mysql_deepmerge, type: :rvalue, doc: <<-'ENDHEREDOC') do |args|
-    Recursively merges two or more hashes together and returns the resulting hash.
-
-    For example:
+    @summary Recursively merges two or more hashes together and returns the resulting hash.
 
+    @example
         $hash1 = {'one' => 1, 'two' => 2, 'three' => { 'four' => 4 } }
         $hash2 = {'two' => 'dos', 'three' => { 'five' => 5 } }
         $merged_hash = mysql_deepmerge($hash1, $hash2)
         # The resulting hash is equivalent to:
         # $merged_hash = { 'one' => 1, 'two' => 'dos', 'three' => { 'four' => 4, 'five' => 5 } }
 
-    When there is a duplicate key that is a hash, they are recursively merged.
-    When there is a duplicate key that is not a hash, the key in the rightmost hash will "win."
-    When there are conficting uses of dashes and underscores in two keys (which mysql would otherwise equate),
+    - When there is a duplicate key that is a hash, they are recursively merged.
+    - When there is a duplicate key that is not a hash, the key in the rightmost hash will "win."
+    - When there are conficting uses of dashes and underscores in two keys (which mysql would otherwise equate),
       the rightmost style will win.
 
+    @return [Hash]
     ENDHEREDOC
 
-    warning('Deprecation: mysql_deepmerge() is deprecated, please use mysql::deepmerge() instead.')
-
     if args.length < 2
       raise Puppet::ParseError, _('mysql_deepmerge(): wrong number of arguments (%{args_length}; must be at least 2)') % { args_length: args.length }
     end

lib/puppet/parser/functions/mysql_dirname.rb

@@ -1,12 +1,16 @@
-# Returns the dirname of a path.
 module Puppet::Parser::Functions
   newfunction(:mysql_dirname, type: :rvalue, doc: <<-EOS
-    Returns the dirname of a path.
+    @summary
+      Returns the dirname of a path
+
+    @param [String] path
+      Path to find the dirname for.
+
+    @return [String]
+      Directory name of path.
     EOS
              ) do |arguments|
 
-    warning('Deprecation: mysql_dirname() is deprecated, please use mysql::dirname() instead.')
-
     if arguments.empty?
       raise Puppet::ParseError, _('mysql_dirname(): Wrong number of arguments given (%{args_length} for 1)') % { args_length: args.length }
     end

lib/puppet/parser/functions/mysql_password.rb

@@ -1,14 +1,15 @@
 require 'digest/sha1'
-# Returns the mysql password hash from the clear text password.
-# Hash a string as mysql's "PASSWORD()" function would do it
 module Puppet::Parser::Functions
   newfunction(:mysql_password, type: :rvalue, doc: <<-EOS
-    Returns the mysql password hash from the clear text password.
+    @summary
+      Hash a string as mysql's "PASSWORD()" function would do it
+
+    @param [String] password Plain text password.
+
+    @return [String] the mysql password hash from the clear text password.
     EOS
              ) do |args|
 
-    warning('Deprecation: mysql_password() is deprecated, please use mysql::password() instead.')
-
     if args.size != 1
       raise Puppet::ParseError, _('mysql_password(): Wrong number of arguments given (%{args_length} for 1)') % { args_length: args.length }
     end

lib/puppet/parser/functions/mysql_strip_hash.rb

@@ -6,8 +6,6 @@ module Puppet::Parser::Functions
 EOS
              ) do |args|
 
-    warning('Deprecation: mysql_strip_hash() is deprecated, please use mysql::strip_hash() instead.')
-
     hash = args[0]
     unless hash.is_a?(Hash)
       raise(Puppet::ParseError, _('mysql_strip_hash(): Requires a hash to work.'))