Merge pull request #1068 from hunner/eputnam-strings

(PDOC-210) add Puppet Strings documentation

Author: hunner

README.md

@@ -1,21 +1,20 @@
-# Recursively merges two or more hashes together and returns the resulting hash.
-module Puppet::Parser::Functions
+module Puppet::Parser::Functions # rubocop:disable Style/Documentation
   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
 
     if args.length < 2

REFERENCE.md

@@ -1,7 +1,13 @@
-# Returns the dirname of a path.
-module Puppet::Parser::Functions
+module Puppet::Parser::Functions # rubocop:disable Style/Documentation
   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|
 

lib/puppet/parser/functions/mysql_deepmerge.rb

@@ -1,9 +1,12 @@
 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
+module Puppet::Parser::Functions # rubocop:disable Style/Documentation
   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|
 

lib/puppet/parser/functions/mysql_dirname.rb

@@ -1,5 +1,10 @@
 Puppet::Type.newtype(:mysql_database) do
-  @doc = 'Manage MySQL databases.'
+  @doc = <<-PUPPET
+    @summary
+      Manage a MySQL database.
+
+    @api private
+  PUPPET
 
   ensurable
 

lib/puppet/parser/functions/mysql_password.rb

@@ -1,5 +1,10 @@
 Puppet::Type.newtype(:mysql_datadir) do
-  @doc = 'Manage MySQL datadirs with mysql_install_db OR mysqld (5.7.6 and above).'
+  @doc = <<-PUPPET
+    @summary
+      Manage MySQL datadirs with mysql_install_db OR mysqld (5.7.6 and above).
+
+    @api private
+    PUPPET
 
   ensurable
 

lib/puppet/type/mysql_database.rb

@@ -1,6 +1,10 @@
-# This has to be a separate type to enable collecting
 Puppet::Type.newtype(:mysql_grant) do
-  @doc = "Manage a MySQL user's rights."
+  @doc = <<-PUPPET
+    @summary
+      Manage a MySQL user's rights.
+
+    @api private
+    PUPPET
   ensurable
 
   autorequire(:file) { '/root/.my.cnf' }

lib/puppet/type/mysql_datadir.rb

@@ -1,5 +1,14 @@
 Puppet::Type.newtype(:mysql_plugin) do
-  @doc = 'Manage MySQL plugins.'
+  @doc = <<-PUPPET
+    @summary
+      Manage MySQL plugins.
+
+    @example
+      mysql_plugin { 'some_plugin':
+        soname => 'some_pluginlib.so',
+      }
+
+  PUPPET
 
   ensurable
 

lib/puppet/type/mysql_grant.rb

@@ -1,6 +1,11 @@
 # This has to be a separate type to enable collecting
 Puppet::Type.newtype(:mysql_user) do
-  @doc = 'Manage a MySQL user. This includes management of users password as well as privileges.'
+  @doc = <<-PUPPET
+    @summary
+      Manage a MySQL user. This includes management of users password as well as privileges.
+
+    @api private
+    PUPPET
 
   ensurable