Add puppet-strings docs

lib/puppet/type/proxy_mysql_galera_hostgroup.rb

@@ -29,6 +29,7 @@ def self.title_patterns
   end
 
   ensurable do
+    desc 'Manage the state of this type.'
     defaultvalues
     defaultto :present
   end

manifests/admin_credentials.pp

@@ -1,7 +1,6 @@
-# == Class proxysql::admin_credentials
-#
-# This class is called from proxysql for service config.
+# @summary This class is called from proxysql for service config.
 #
+# @api private
 class proxysql::admin_credentials {
   if $proxysql::manage_mycnf_file {
     $mycnf_file_name = $proxysql::mycnf_file_name

manifests/config.pp

@@ -1,7 +1,6 @@
-# == Class proxysql::config
-#
-# This class is called from proxysql for service config.
+# @summary This class is called from proxysql for service config.
 #
+# @api private
 class proxysql::config {
   $config_settings = $proxysql::config_settings
   $proxy_config_file = $proxysql::proxy_config_file

manifests/configure.pp

@@ -1,7 +1,6 @@
-# == Class proxysql::configure
-#
-# This class is called from proxysql for all proxy configuration.
+# @summary This class is called from proxysql for all proxy configuration.
 #
+# @api private
 class proxysql::configure {
   if $proxysql::mysql_servers {
     $proxysql::mysql_servers.each |$server| {

manifests/init.pp

@@ -1,185 +1,177 @@
-# Class: proxysql
-# ===========================
-#
-# Full description of class proxysql here.
-#
-# Parameters
-# ----------
-#
-# * `package_name`
+# @summary This class is called from proxysql for service config.
+# @param package_name
 #   The name of the ProxySQL package in your package manager. Defaults to 'proxysql'
 #
-# * `package_ensure`
+# @param package_ensure
 #   The ensure of the ProxySQL package resource. Defaults to 'installed'
 #
-# * `service_name`
+# @param service_name
 #   The name of the ProxySQL service resource. Defaults to 'proxysql'
 #
-# * `service_ensure`
+# @param service_ensure
 #   The ensure of the ProxySQL service resource. Defaults to 'running'
 #
-# * `datadir`
+# @param datadir
 #   The directory where ProxySQL will store its data. Defaults to '/var/lib/proxysql'
 #
-# * `datadir_mode`
+# @param datadir_mode
 #   The filesystem mode for the `datadir`. Defaults to '0600'
 #
-# * `errorlog_file`
+# @param errorlog_file
 #   The File where ProxySQL will store its error logs. Defaults to '/var/lib/proxysql/proxysql.log'. Available from ProxySQL v2.0.0
 #
-# * `errorlog_file_mode`
+# @param errorlog_file_mode
 #   The filesystem mode for the `errorlog_file`. Defaults to '0600'. Available from ProxySQL v2.0.0
 #
-# * `errorlog_file_owner`
+# @param errorlog_file_owner
 #   Owner of the `errorlog_file`. Defaults to 'proxysql'. Available from ProxySQL v2.0.0
 #
-# * `errorlog_file_group`
+# @param errorlog_file_group
 #   Group of the `errorlog_file`. Defaults to 'proxysql'. Available from ProxySQL v2.0.0
 #
-# * `manage_selinux`
+# @param manage_selinux
 #   Whether to create the required selinux rules for logrotate to work.  Defaults to `true`, but is only applicable to systems where SELinux is active (`enforcing` or `permissive`).
 #   This parameter also requires the `puppet/selinux` module to be installed.
 #
-# * `manage_mysql_client`
+# @param manage_mysql_client
 #   Whether to include the mysql::client class. Defaults to `true`
 #   You may have mysql::client included or managed with different parameters elsewhere in your catalogue.
 #
-# * `listen_ip`
+# @param listen_ip
 #   The ip where the ProxySQL service will listen on. Defaults to '0.0.0.0' aka all configured IP's on the machine
 #
-# * `listen_port`
+# @param listen_port
 #   The port where the ProxySQL service will listen on. Defaults to '6033'
 #
-# * `listen_socket`
+# @param listen_socket
 #   The socket where the ProxySQL service will listen on. Defaults to '/tmp/proxysql.sock'
 #
-# * `admin_username`
+# @param admin_username
 #   The username to connect to the ProxySQL admin interface. Defaults to 'admin'
 #
-# * `admin_password`
+# @param admin_password
 #   The password to connect to the ProxySQL admin interface. Defaults to 'admin'
 #
-# * `stats_username`
+# @param stats_username
 #   The username to connect with read-only permissions to the ProxySQL admin interface. Defaults to 'stats'
 #
-# * `stats_password`
+# @param stats_password
 #   The password to connect with read-only permissions to the ProxySQL admin interface. Defaults to 'stats'
 #
-# * `admin_listen_ip`
+# @param admin_listen_ip
 #   The ip where the ProxySQL admin interface will listen on. Defaults to '127.0.0.1'
 #
-# * `admin_listen_port`
+# @param admin_listen_port
 #   The port where the ProxySQL admin interface  will listen on. Defaults to '6032'
 #
-# * `admin_listen_socket`
+# @param admin_listen_socket
 #   The socket where the ProxySQL admin interface  will listen on. Changing this on a running system will result in failing runs.
 #   Defaults to '/tmp/proxysql_admin.sock'
 #
-# * `monitor_username`
+# @param monitor_username
 #   The username ProxySQL will use to connect to the configured mysql_servers. Defaults to 'monitor'
 #
-# * `monitor_password`
+# @param monitor_password
 #   The password ProxySQL will use to connect to the configured mysql_servers. Defaults to 'monitor'
 #
-# * `config_file`
+# @param config_file
 #   The file where the ProxySQL configuration is saved. This will only be configured if `manage_config_file` is set to `true`.
 #   Defaults to '/etc/proxysql.cnf'
 #
-# * `manage_config_file`
+# @param manage_config_file
 #   Determines whether this module will configure the ProxySQL configuration file. Defaults to 'true'
 #
-# * `mycnf_file_name`
+# @param mycnf_file_name
 #   Path of the my.cnf file where the connections details for the admin interface is save. This is required for the providers to work.
 #   This will only be configured if `manage_mycnf_file` is set to `true`. Defaults to '/root/.my.cnf'
 #
-# * `manage_mycnf_file`
+# @param manage_mycnf_file
 #   Determines whether this module will configure the my.cnf file to connect to the admin interface.
 #   This is required for the providers to work. Defaults to 'true'
 #
-# * `restart`
+# @param restart
 #   Determines whether this module will restart ProxySQL after reconfiguring the config file. Defaults to 'false'
 #
-# * `load_to_runtime`
+# @param load_to_runtime
 #   Specifies whether te managed ProxySQL resources should be immediately loaded to the active runtime. Boolean, defaults to 'true'.
 #
-# * `save_to_disk`
+# @param save_to_disk
 #   Specifies whether te managed ProxySQL resources should be immediately save to disk. Boolean, defaults to 'true'.
 #
-# * `manage_repo`
+# @param manage_repo
 #   Determines whether this module will manage the repositories where ProxySQL might be. Defaults to 'true'
 #
-# * `version`
+# @param version
 #   The version of proxysql being managed.  This parameter affects the repository configured when `manage_repo == true` and how the service is managed.
 #   It does not affect the package version being installed.  It is used as a hint to the puppet module on how to configure proxysql. To control the exact version
 #   deployed, use `package_name` or `package_source`.  Defaults to the version currently installed, or `2.0.7` if the `proxysql_version` fact is not yet
 #   available.
 #
-# * `package_source`
+# @param package_source
 #   location of a proxysql package.  When specified, this package will be installed with the `package\_provider` and the `manage_repo` setting will be ignored.
 #   Since version 4 of this module, this defaults to `undef` and needs to be specified when you don't want to use a package from a repository.
 #
-# * `package_provider`
+# @param package_provider
 #   provider for `package_source`. defaults to `dpkg` for debian-based, and `rpm` for redhat systems.
 #
-# * `package_checksum_value`
+# @param package_checksum_value
 #   The checksum of the package. Optional and only applicable when `package_source` is provided.
 #
-# * `package_checksum_type`
+# @param package_checksum_type
 #   The 'type' of `package_checksum_value`. Optional and only applicable when `package_checksum_value` is provided.
 #
-# * `sys_owner`
+# @param sys_owner
 #   owner of the datadir and config_file, defaults to root or proxysql depending on `version`
 #
-# * `sys_group`
+# @param sys_group
 #   group of the datadir and config_file, defaults to root or proxysql depending on `version`
 #
-# * `override_config_settings`
+# @param override_config_settings
 #   Which configuration variables should be overriden. Hash, defaults to {} (empty hash).
 #
-# * `cluster_name`
+# @param cluster_name
 #   If set, proxysql_servers with the same cluster_name will be automatically added to the same cluster and will
 #   synchronize their configuration parameters. Defaults to undef
 #
-# * `cluster_username`
+# @param cluster_username
 #   The username ProxySQL will use to connect to the configured mysql_clusters
 #   Defaults to 'cluster'
 #
-# * `cluster_password`
+# @param cluster_password
 #   The password ProxySQL will use to connect to the configured mysql_clusters. Defaults to 'cluster'
 #
-# * `mysql_client_package_name`
+# @param mysql_client_package_name
 #   The name of the mysql client package in your package manager. Defaults to undef
 #
-# * `manage_hostgroup_for_servers`
+# @param manage_hostgroup_for_servers
 #   Determines whether this module will manage hostgroup_id for mysql_servers.
 #   If false - it will skip difference in this value between manifest and defined in ProxySQL. Defaults to 'true'
 #
-# * `mysql_servers`
+# @param mysql_servers
 #   Array of mysql_servers, that will be created in ProxySQL. Defaults to undef
 #
-# * `mysql_users`
+# @param mysql_users
 #   Array of mysql_users, that will be created in ProxySQL. Defaults to undef
 #
-# * `mysql_hostgroups`
+# @param mysql_hostgroups
 #   Array of mysql_hostgroups, that will be created in ProxySQL. Defaults to undef
 #
-# * `mysql_rules`
+# @param mysql_rules
 #   Array of mysql_rules, that will be created in ProxySQL. Defaults to undef
 #
-# * `schedulers`
+# @param schedulers
 #   Array of schedulers, that will be created in ProxySQL. Defaults to undef
 #
-# * `split_config`
+# @param split_config
 #   If set, ProxySQL config file will be split in 2: main config file with admin and mysql variables
 #   and proxy config file with servers\users\hostgroups\scheduler params. Defaults to false
 #
-# * `proxy_config_file`
+# @param proxy_config_file
 #   The file where servers\users\hostgroups\scheduler\rules params of ProxySQL configuration are saved
 #   This will only be configured if `split_config` is set to `true`. Defaults to 'proxysql_proxy.cnf'
 #
-# * `manage_proxy_config_file`
+# @param manage_proxy_config_file
 #   Determines whether this module will update the ProxySQL proxy configuration file. Defaults to 'true'
-#
 class proxysql (
   Optional[String[1]] $cluster_name = undef,
   String $package_name = 'proxysql',

manifests/install.pp

@@ -1,7 +1,6 @@
-# == Class proxysql::install
-#
-# This class is called from proxysql for install.
+# @summary This class is called from proxysql for install.
 #
+# @api private
 class proxysql::install {
   if $proxysql::package_source {
     case $facts['os']['family'] {

manifests/params.pp

@@ -1,8 +1,6 @@
-# == Class proxysql::params
-#
-# This class is meant to be called from proxysql.
-# It sets variables according to platform.
+# @summary It sets variables according to platform.
 #
+# @api private
 class proxysql::params {
   $datadir = '/var/lib/proxysql'
 

manifests/prerequisites.pp

@@ -1,8 +1,6 @@
-# Class: proxysql::prerequisites
-# ===========================
-#
-# Manage the prerequisites where the ProxySQL package might be
+# @summary Manage the prerequisites where the ProxySQL package might be.
 #
+# @api private
 class proxysql::prerequisites inherits proxysql {
   if $proxysql::sys_owner != 'root' { # let's assume that 'root' will exist and not touch that...
     group { $proxysql::sys_group:

manifests/reload_config.pp

@@ -1,7 +1,6 @@
-# == Class proxysql::reload_config
-#
-# This class is called from proxysql to update config if it changed.
+# @summary This class is called from proxysql to update config if it changed.
 #
+# @api private
 class proxysql::reload_config {
   $subscribe = $proxysql::split_config ? {
     true  => [File['proxysql-config-file'], File['proxysql-proxy-config-file']],

manifests/repo.pp

@@ -1,8 +1,6 @@
-# Class: proxysql::repo
-# ===========================
-#
-# Manage the repos where the ProxySQL package might be
+# @summary Manage the repos where the ProxySQL package might be.
 #
+# @api private
 class proxysql::repo {
   assert_private()
 

manifests/selinux.pp

@@ -1,4 +1,4 @@
-# @summary Adds selinux configuration needed for logrotate to work
+# @summary Adds selinux configuration needed for logrotate to work.
 #
 # @api private
 class proxysql::selinux {

manifests/service.pp

@@ -1,8 +1,6 @@
-# == Class proxysql::service
-#
-# This class is meant to be called from proxysql.
-# It ensure the service is running.
+# @summary This class ensures that the service is running.
 #
+# @api private
 class proxysql::service {
   assert_private()
 

types/galerahostgroup.pp

@@ -1,3 +1,4 @@
+# @summary Represents an entry in the ProxySQL `mysql_galera_hostgroups` admin table.
 type Proxysql::GaleraHostgroup = Array[Hash[String, Struct[{ writer                     => Integer[0],
                                                              backup                     => Integer[0],
                                                              reader                     => Integer[0],