Skip to content

Commit f0663f3

Browse files
eputnameputnam
committed
(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.
1 parent 667c2c7 commit f0663f3

37 files changed

+1599
-944
lines changed

‎README.md

+1-903
Large diffs are not rendered by default.

‎REFERENCE.md

+1,180
Large diffs are not rendered by default.

‎lib/puppet/parser/functions/mysql_deepmerge.rb

+6-7
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,20 @@
1-
# Recursively merges two or more hashes together and returns the resulting hash.
21
module Puppet::Parser::Functions
32
newfunction(:mysql_deepmerge, type: :rvalue, doc: <<-'ENDHEREDOC') do |args|
4-
Recursively merges two or more hashes together and returns the resulting hash.
5-
6-
For example:
3+
@summary Recursively merges two or more hashes together and returns the resulting hash.
74
5+
@example
86
$hash1 = {'one' => 1, 'two' => 2, 'three' => { 'four' => 4 } }
97
$hash2 = {'two' => 'dos', 'three' => { 'five' => 5 } }
108
$merged_hash = mysql_deepmerge($hash1, $hash2)
119
# The resulting hash is equivalent to:
1210
# $merged_hash = { 'one' => 1, 'two' => 'dos', 'three' => { 'four' => 4, 'five' => 5 } }
1311
14-
When there is a duplicate key that is a hash, they are recursively merged.
15-
When there is a duplicate key that is not a hash, the key in the rightmost hash will "win."
16-
When there are conficting uses of dashes and underscores in two keys (which mysql would otherwise equate),
12+
- When there is a duplicate key that is a hash, they are recursively merged.
13+
- When there is a duplicate key that is not a hash, the key in the rightmost hash will "win."
14+
- When there are conficting uses of dashes and underscores in two keys (which mysql would otherwise equate),
1715
the rightmost style will win.
1816
17+
@return [Hash]
1918
ENDHEREDOC
2019

2120
if args.length < 2

‎lib/puppet/parser/functions/mysql_dirname.rb

+8-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,13 @@
1-
# Returns the dirname of a path.
21
module Puppet::Parser::Functions
32
newfunction(:mysql_dirname, type: :rvalue, doc: <<-EOS
4-
Returns the dirname of a path.
3+
@summary
4+
Returns the dirname of a path
5+
6+
@param [String] path
7+
Path to find the dirname for.
8+
9+
@return [String]
10+
Directory name of path.
511
EOS
612
) do |arguments|
713

‎lib/puppet/parser/functions/mysql_password.rb

+6-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,12 @@
11
require 'digest/sha1'
2-
# Returns the mysql password hash from the clear text password.
3-
# Hash a string as mysql's "PASSWORD()" function would do it
42
module Puppet::Parser::Functions
53
newfunction(:mysql_password, type: :rvalue, doc: <<-EOS
6-
Returns the mysql password hash from the clear text password.
4+
@summary
5+
Hash a string as mysql's "PASSWORD()" function would do it
6+
7+
@param [String] password Plain text password.
8+
9+
@return [String] the mysql password hash from the clear text password.
710
EOS
811
) do |args|
912

‎lib/puppet/type/mysql_database.rb

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
Puppet::Type.newtype(:mysql_database) do
2-
@doc = 'Manage MySQL databases.'
2+
@doc = <<-PUPPET
3+
@summary
4+
Manage a MySQL database.
5+
6+
@api private
7+
PUPPET
38

49
ensurable
510

‎lib/puppet/type/mysql_datadir.rb

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
Puppet::Type.newtype(:mysql_datadir) do
2-
@doc = 'Manage MySQL datadirs with mysql_install_db OR mysqld (5.7.6 and above).'
2+
@doc = <<-PUPPET
3+
@summary
4+
Manage MySQL datadirs with mysql_install_db OR mysqld (5.7.6 and above).
5+
6+
@api private
7+
PUPPET
38

49
ensurable
510

‎lib/puppet/type/mysql_grant.rb

+6-2
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,10 @@
1-
# This has to be a separate type to enable collecting
21
Puppet::Type.newtype(:mysql_grant) do
3-
@doc = "Manage a MySQL user's rights."
2+
@doc = <<-PUPPET
3+
@summary
4+
Manage a MySQL user's rights.
5+
6+
@api private
7+
PUPPET
48
ensurable
59

610
autorequire(:file) { '/root/.my.cnf' }

‎lib/puppet/type/mysql_plugin.rb

+10-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
Puppet::Type.newtype(:mysql_plugin) do
2-
@doc = 'Manage MySQL plugins.'
2+
@doc = <<-PUPPET
3+
@summary
4+
Manage MySQL plugins.
5+
6+
@example
7+
mysql_plugin { 'some_plugin':
8+
soname => 'some_pluginlib.so',
9+
}
10+
11+
PUPPET
312

413
ensurable
514

‎lib/puppet/type/mysql_user.rb

+6-1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# This has to be a separate type to enable collecting
22
Puppet::Type.newtype(:mysql_user) do
3-
@doc = 'Manage a MySQL user. This includes management of users password as well as privileges.'
3+
@doc = <<-PUPPET
4+
@summary
5+
Manage a MySQL user. This includes management of users password as well as privileges.
6+
7+
@api private
8+
PUPPET
49

510
ensurable
611

‎manifests/backup/mysqlbackup.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# See README.me for usage.
1+
# @summary
2+
# Manage the mysqlbackup client.
3+
#
4+
# @api private
5+
#
26
class mysql::backup::mysqlbackup (
37
$backupuser = '',
48
$backuppassword = '',

‎manifests/backup/mysqldump.pp

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# See README.me for usage.
1+
# @summary
2+
# "Provider" for mysqldump
3+
# @api private
4+
#
25
class mysql::backup::mysqldump (
36
$backupuser = '',
47
$backuppassword = '',

‎manifests/backup/xtrabackup.pp

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,7 @@
1-
# See README.me for usage.
1+
# @summary
2+
# "Provider" for Percona XtraBackup
3+
# @api private
4+
#
25
class mysql::backup::xtrabackup (
36
$xtrabackup_package_name = $mysql::params::xtrabackup_package_name,
47
$backupuser = undef,

‎manifests/bindings.pp

+69-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,72 @@
1-
# See README.md.
1+
# @summary
2+
# Parent class for MySQL bindings.
3+
#
4+
# @example Install Ruby language bindings
5+
# class { 'mysql::bindings':
6+
# ruby_enable => true,
7+
# ruby_package_ensure => 'present',
8+
# ruby_package_name => 'ruby-mysql-2.7.1-1mdv2007.0.sparc.rpm',
9+
# ruby_package_provider => 'rpm',
10+
# }
11+
# @param install_options
12+
# 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).
13+
# @param java_enable
14+
# Specifies whether `::mysql::bindings::java` should be included. Valid values are `true`, `false`.
15+
# @param perl_enable
16+
# Specifies whether `mysql::bindings::perl` should be included. Valid values are `true`, `false`.
17+
# @param php_enable
18+
# Specifies whether `mysql::bindings::php` should be included. Valid values are `true`, `false`.
19+
# @param python_enable
20+
# Specifies whether `mysql::bindings::python` should be included. Valid values are `true`, `false`.
21+
# @param ruby_enable
22+
# Specifies whether `mysql::bindings::ruby` should be included. Valid values are `true`, `false`.
23+
# @param client_dev
24+
# Specifies whether `::mysql::bindings::client_dev` should be included. Valid values are `true`', `false`.
25+
# @param daemon_dev
26+
# Specifies whether `::mysql::bindings::daemon_dev` should be included. Valid values are `true`, `false`.
27+
# @param java_package_ensure
28+
# 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`.
29+
# @param java_package_name
30+
# The name of the Java package to install. Only applies if `java_enable => true`.
31+
# @param java_package_provider
32+
# The provider to use to install the Java package. Only applies if `java_enable => true`.
33+
# @param perl_package_ensure
34+
# 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`.
35+
# @param perl_package_name
36+
# The name of the Perl package to install. Only applies if `perl_enable => true`.
37+
# @param perl_package_provider
38+
# The provider to use to install the Perl package. Only applies if `perl_enable => true`.
39+
# @param php_package_ensure
40+
# 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`.
41+
# @param php_package_name
42+
# The name of the PHP package to install. Only applies if `php_enable => true`.
43+
# @param php_package_provider
44+
# The provider to use to install the PHP package. Only applies if `php_enable => true`.
45+
# @param python_package_ensure
46+
# 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`.
47+
# @param python_package_name
48+
# The name of the Python package to install. Only applies if `python_enable => true`.
49+
# @param python_package_provider
50+
# The provider to use to install the Python package. Only applies if `python_enable => true`.
51+
# @param ruby_package_ensure
52+
# 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`.
53+
# @param ruby_package_name
54+
# The name of the Ruby package to install. Only applies if `ruby_enable => true`.
55+
# @param ruby_package_provider
56+
# What provider should be used to install the package.
57+
# @param client_dev_package_ensure
58+
# 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`.
59+
# @param client_dev_package_name
60+
# The name of the client_dev package to install. Only applies if `client_dev => true`.
61+
# @param client_dev_package_provider
62+
# The provider to use to install the client_dev package. Only applies if `client_dev => true`.
63+
# @param daemon_dev_package_ensure
64+
# 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`.
65+
# @param daemon_dev_package_name
66+
# The name of the daemon_dev package to install. Only applies if `daemon_dev => true`.
67+
# @param daemon_dev_package_provider
68+
# The provider to use to install the daemon_dev package. Only applies if `daemon_dev => true`.
69+
#
270
class mysql::bindings (
371
$install_options = undef,
472
# Boolean to determine if we should include the classes.

‎manifests/bindings/client_dev.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class
1+
# @summary
2+
# Private class for installing client development bindings
3+
#
4+
# @api private
5+
#
26
class mysql::bindings::client_dev {
37

48
if $mysql::bindings::client_dev_package_name {

‎manifests/bindings/daemon_dev.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class
1+
# @summary
2+
# Private class for installing daemon development bindings
3+
#
4+
# @api private
5+
#
26
class mysql::bindings::daemon_dev {
37

48
if $mysql::bindings::daemon_dev_package_name {

‎manifests/bindings/java.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class
1+
# @summary
2+
# Private class for installing java language bindings.
3+
#
4+
# @api private
5+
#
26
class mysql::bindings::java {
37

48
package { 'mysql-connector-java':

‎manifests/bindings/perl.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class
1+
# @summary
2+
# Private class for installing perl language bindings.
3+
#
4+
# @api private
5+
#
26
class mysql::bindings::perl {
37

48
package{ 'perl_mysql':

‎manifests/bindings/php.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class: See README.md
1+
# @summary
2+
# Private class for installing php language bindings
3+
#
4+
# @api private
5+
#
26
class mysql::bindings::php {
37

48
package { 'php-mysql':

‎manifests/bindings/python.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class
1+
# @summary
2+
# Private class for installing python language bindings
3+
#
4+
# @api private
5+
#
26
class mysql::bindings::python {
37

48
package { 'python-mysqldb':

‎manifests/bindings/ruby.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class
1+
# @summary
2+
# Private class for installing ruby language bindings
3+
#
4+
# @api private
5+
#
26
class mysql::bindings::ruby {
37

48
package{ 'ruby_mysql':

‎manifests/client.pp

+20
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,23 @@
1+
# @summary
2+
# Installs and configures the MySQL client.
3+
#
4+
# @example Install the MySQL client
5+
# class {'::mysql::client':
6+
# package_name => 'mysql-client',
7+
# package_ensure => 'present',
8+
# bindings_enable => true,
9+
# }
10+
#
11+
# @param bindings_enable
12+
# Whether to automatically install all bindings. Valid values are `true`, `false`. Default to `false`.
13+
# @param install_options
14+
# Array of install options for managed package resources. You must pass the appropriate options for the package manager.
15+
# @param package_ensure
16+
# Whether the MySQL package should be present, absent, or a specific version. Valid values are 'present', 'absent', or 'x.y.z'.
17+
# @param package_manage
18+
# Whether to manage the MySQL client package. Defaults to `true`.
19+
# @param package_name
20+
# The name of the MySQL client package to install.
121
#
222
class mysql::client (
323
$bindings_enable = $mysql::params::bindings_enable,

‎manifests/client/install.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# See README.md.
1+
# @summary
2+
# Private class for MySQL client install.
3+
#
4+
# @api private
5+
#
26
class mysql::client::install {
37

48
if $mysql::client::package_manage {

‎manifests/db.pp

+36-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,39 @@
1-
# See README.md for details.
1+
# @summary
2+
# Create and configure a MySQL database.
3+
#
4+
# @example Create a database
5+
# mysql::db { 'mydb':
6+
# user => 'myuser',
7+
# password => 'mypass',
8+
# host => 'localhost',
9+
# grant => ['SELECT', 'UPDATE'],
10+
# }
11+
#
12+
# @param user
13+
# The user for the database you're creating.
14+
# @param password
15+
# The password for $user for the database you're creating.
16+
# @param dbname
17+
# The name of the database to create.
18+
# @param charset
19+
# The character set for the database.
20+
# @param collate
21+
# The collation for the database.
22+
# @param host
23+
# The host to use as part of user@host for grants.
24+
# @param grant
25+
# The privileges to be granted for user@host on the database.
26+
# @param sql
27+
# 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.
28+
# @param enforce_sql
29+
# Specifies whether executing the sqlfiles should happen on every run. If set to false, sqlfiles only run once.
30+
# @param ensure
31+
# Specifies whether to create the database. Valid values are 'present', 'absent'. Defaults to 'present'.
32+
# @param import_timeout
33+
# Timeout, in seconds, for loading the sqlfiles. Defaults to 300.
34+
# @param import_cat_cmd
35+
# Command to read the sqlfile for importing the database. Useful for compressed sqlfiles. For example, you can use 'zcat' for .gz files.
36+
#
237
define mysql::db (
338
$user,
439
$password,

‎manifests/params.pp

+5-1
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
1-
# Private class: See README.md.
1+
# @summary
2+
# Params class.
3+
#
4+
# @api private
5+
#
26
class mysql::params {
37

48
$manage_config_file = true

0 commit comments

Comments
 (0)