(PDOC-210) add Puppet Strings documentation

Part of the Puppet Strings effort is having an example module out before
version 2.0.0 is released. This adds 'correct' Strings documentation to
this entire module and moves the Reference section of the README to
REFERENCE.md.

Author: eputnam

README.md

@@ -1,21 +1,20 @@
-# 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
 
     if args.length < 2

REFERENCE.md

@@ -1,7 +1,13 @@
-# 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|
 

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
   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