(PDOC-210) add Puppet Strings documentation

lib/puppet/parser/functions/mysql_deepmerge.rb

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

lib/puppet/parser/functions/mysql_dirname.rb

@@ -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_password.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/type/mysql_database.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/type/mysql_datadir.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_grant.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_plugin.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_user.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
 

manifests/backup/mysqlbackup.pp

@@ -1,4 +1,8 @@
-# See README.me for usage.
+# @summary
+#   Manage the mysqlbackup client.
+#
+# @api private
+#
 class mysql::backup::mysqlbackup (
   $backupuser         = '',
   $backuppassword     = '',

manifests/backup/mysqldump.pp

@@ -1,4 +1,7 @@
-# See README.me for usage.
+# @summary
+#   "Provider" for mysqldump
+# @api private
+#
 class mysql::backup::mysqldump (
   $backupuser         = '',
   $backuppassword     = '',

manifests/backup/xtrabackup.pp

@@ -1,4 +1,7 @@
-# See README.me for usage.
+# @summary
+#   "Provider" for Percona XtraBackup
+# @api private
+#
 class mysql::backup::xtrabackup (
   $xtrabackup_package_name = $mysql::params::xtrabackup_package_name,
   $backupuser              = undef,

manifests/bindings.pp

@@ -1,4 +1,72 @@
-# See README.md.
+# @summary
+#   Parent class for MySQL bindings.
+#
+# @example Install Ruby language bindings
+#   class { 'mysql::bindings':
+#     ruby_enable           => true,
+#     ruby_package_ensure   => 'present',
+#     ruby_package_name     => 'ruby-mysql-2.7.1-1mdv2007.0.sparc.rpm',
+#     ruby_package_provider => 'rpm',
+#   }
+# @param install_options
+#   Passes `install_options` array to managed package resources. You must pass the [appropriate options](https://docs.puppetlabs.com/references/latest/type.html#package-attribute-install_options) for the package manager(s).
+# @param java_enable
+#   Specifies whether `::mysql::bindings::java` should be included. Valid values are `true`, `false`.
+# @param perl_enable
+#   Specifies whether `mysql::bindings::perl` should be included. Valid values are `true`, `false`.
+# @param php_enable
+#   Specifies whether `mysql::bindings::php` should be included. Valid values are `true`, `false`.
+# @param python_enable
+#   Specifies whether `mysql::bindings::python` should be included. Valid values are `true`, `false`.
+# @param ruby_enable
+#   Specifies whether `mysql::bindings::ruby` should be included. Valid values are `true`, `false`.
+# @param client_dev
+#   Specifies whether `::mysql::bindings::client_dev` should be included. Valid values are `true`', `false`.
+# @param daemon_dev
+#   Specifies whether `::mysql::bindings::daemon_dev` should be included. Valid values are `true`, `false`.
+# @param java_package_ensure
+#   Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `java_enable => true`.
+# @param java_package_name
+#   The name of the Java package to install. Only applies if `java_enable => true`.
+# @param java_package_provider
+#   The provider to use to install the Java package. Only applies if `java_enable => true`.
+# @param perl_package_ensure
+#   Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `perl_enable => true`.
+# @param perl_package_name
+#   The name of the Perl package to install. Only applies if `perl_enable => true`.
+# @param perl_package_provider
+#   The provider to use to install the Perl package. Only applies if `perl_enable => true`.
+# @param php_package_ensure
+#   Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `php_enable => true`.
+# @param php_package_name
+#   The name of the PHP package to install. Only applies if `php_enable => true`.
+# @param php_package_provider
+#   The provider to use to install the PHP package. Only applies if `php_enable => true`.
+# @param python_package_ensure
+#   Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `python_enable => true`.
+# @param python_package_name
+#   The name of the Python package to install. Only applies if `python_enable => true`.
+# @param python_package_provider
+#   The provider to use to install the Python package. Only applies if `python_enable => true`.
+# @param ruby_package_ensure
+#   Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `ruby_enable => true`.
+# @param ruby_package_name
+#   The name of the Ruby package to install. Only applies if `ruby_enable => true`.
+# @param ruby_package_provider
+#   What provider should be used to install the package.
+# @param client_dev_package_ensure
+#   Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `client_dev => true`.
+# @param client_dev_package_name
+#   The name of the client_dev package to install. Only applies if `client_dev => true`.
+# @param client_dev_package_provider
+#   The provider to use to install the client_dev package. Only applies if `client_dev => true`.
+# @param daemon_dev_package_ensure
+#   Whether the package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'. Only applies if `daemon_dev => true`.
+# @param daemon_dev_package_name
+#   The name of the daemon_dev package to install. Only applies if `daemon_dev => true`.
+# @param daemon_dev_package_provider
+#   The provider to use to install the daemon_dev package. Only applies if `daemon_dev => true`.
+#
 class mysql::bindings (
   $install_options = undef,
   # Boolean to determine if we should include the classes.

manifests/bindings/client_dev.pp

@@ -1,4 +1,8 @@
-# Private class
+# @summary
+#   Private class for installing client development bindings
+#
+# @api private
+#
 class mysql::bindings::client_dev {
 
   if $mysql::bindings::client_dev_package_name {

manifests/bindings/daemon_dev.pp

@@ -1,4 +1,8 @@
-# Private class
+# @summary
+#   Private class for installing daemon development bindings
+#
+# @api private
+#
 class mysql::bindings::daemon_dev {
 
   if $mysql::bindings::daemon_dev_package_name {

manifests/bindings/java.pp

@@ -1,4 +1,8 @@
-# Private class
+# @summary
+#   Private class for installing java language bindings.
+#
+# @api private
+#
 class mysql::bindings::java {
 
   package { 'mysql-connector-java':

manifests/bindings/perl.pp

@@ -1,4 +1,8 @@
-# Private class
+# @summary
+#   Private class for installing perl language bindings.
+#
+# @api private
+#
 class mysql::bindings::perl {
 
   package{ 'perl_mysql':

manifests/bindings/php.pp

@@ -1,4 +1,8 @@
-# Private class: See README.md
+# @summary
+#   Private class for installing php language bindings
+#
+# @api private
+#
 class mysql::bindings::php {
 
   package { 'php-mysql':

manifests/bindings/python.pp

@@ -1,4 +1,8 @@
-# Private class
+# @summary
+#   Private class for installing python language bindings
+#
+# @api private
+#
 class mysql::bindings::python {
 
   package { 'python-mysqldb':

manifests/bindings/ruby.pp

@@ -1,4 +1,8 @@
-# Private class
+# @summary
+#   Private class for installing ruby language bindings
+#
+# @api private
+#
 class mysql::bindings::ruby {
 
   package{ 'ruby_mysql':

manifests/client.pp

@@ -1,3 +1,23 @@
+# @summary
+#   Installs and configures the MySQL client.
+#
+# @example Install the MySQL client
+#   class {'::mysql::client':
+#     package_name    => 'mysql-client',
+#     package_ensure  => 'present',
+#     bindings_enable => true,
+#   }
+#
+# @param bindings_enable
+#   Whether to automatically install all bindings. Valid values are `true`, `false`. Default to `false`.
+# @param install_options
+#   Array of install options for managed package resources. You must pass the appropriate options for the package manager.
+# @param package_ensure
+#   Whether the MySQL package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'.
+# @param package_manage
+#   Whether to manage the MySQL client package. Defaults to `true`.
+# @param package_name
+#   The name of the MySQL client package to install.
 #
 class mysql::client (
   $bindings_enable = $mysql::params::bindings_enable,

manifests/client/install.pp

@@ -1,4 +1,8 @@
-# See README.md.
+# @summary
+#   Private class for MySQL client install.
+#
+# @api private
+#
 class mysql::client::install {
 
   if $mysql::client::package_manage {

manifests/db.pp

@@ -1,4 +1,39 @@
-# See README.md for details.
+# @summary
+#   Create and configure a MySQL database.
+#
+# @example Create a database
+#   mysql::db { 'mydb':
+#     user     => 'myuser',
+#     password => 'mypass',
+#     host     => 'localhost',
+#     grant    => ['SELECT', 'UPDATE'],
+#   }
+#
+# @param user
+#   The user for the database you're creating.
+# @param password
+#   The password for $user for the database you're creating.
+# @param dbname
+#   The name of the database to create.
+# @param charset
+#   The character set for the database.
+# @param collate
+#   The collation for the database.
+# @param host
+#   The host to use as part of user@host for grants.
+# @param grant
+#   The privileges to be granted for user@host on the database.
+# @param sql
+#   The path to the sqlfile you want to execute. This can be single file specified as string, or it can be an array of strings.
+# @param enforce_sql
+#   Specifies whether executing the sqlfiles should happen on every run. If set to false, sqlfiles only run once.
+# @param ensure
+#   Specifies whether to create the database. Valid values are 'present', 'absent'. Defaults to 'present'.
+# @param import_timeout
+#   Timeout, in seconds, for loading the sqlfiles. Defaults to 300.
+# @param import_cat_cmd
+#   Command to read the sqlfile for importing the database. Useful for compressed sqlfiles. For example, you can use 'zcat' for .gz files.
+#
 define mysql::db (
   $user,
   $password,

manifests/params.pp

@@ -1,4 +1,8 @@
-# Private class: See README.md.
+# @summary
+#   Params class.
+#
+# @api private
+#
 class mysql::params {
 
   $manage_config_file     = true