Update parameter descriptions

Author: Daniel Carabas

REFERENCE.md

@@ -1,4 +1,7 @@
-# @summary Install client cli tool. 
+# @summary Installs PostgreSQL client software. Set the following parameters if you have a custom version you would like to install.
+# 
+# @note
+#  Make sure to add any necessary yum or apt repositories if specifying a custom version.
 #
 # @param file_ensure
 #   Enum['file','absent'].
@@ -7,10 +10,10 @@
 #   Optional. Absolute path for the postgresql connection validation script.
 #
 # @param package_name
-#   String. Client package name.
+#   String. Sets the name of the PostgreSQL client package.
 #
-# @param package_ensure
-#   String. Defaults to 'present'.
+# @param package_ensure 
+#   Enum['present','absent'].
 #
 #
 class postgresql::client (

manifests/client.pp

@@ -1,63 +1,79 @@
 # @summary Class for setting cross-class global overrides.
 #
-# @param client_package_name      
-# @param server_package_name      
-# @param contrib_package_name     
-# @param devel_package_name       
-# @param java_package_name        
-# @param docs_package_name        
-# @param perl_package_name        
-# @param plperl_package_name      
-# @param plpython_package_name    
-# @param python_package_name      
-# @param postgis_package_name     
-#
-# @param service_name             
-# @param service_provider         
-# @param service_status           
-# @param default_database         
+# @note
+#   Most server-specific defaults should be overridden in the postgresql::server class. 
+#   This class should be used only if you are using a non-standard OS, or if you are changing elements that can only be changed here, such as version or manage_package_repo.
+#
+#
+# @param client_package_name  Overrides the default PostgreSQL client package name.    
+# @param server_package_name Overrides the default PostgreSQL server package name.
+# @param contrib_package_name Overrides the default PostgreSQL contrib package name.
+# @param devel_package_name Overrides the default PostgreSQL devel package name.
+# @param java_package_name Overrides the default PostgreSQL java package name.
+# @param docs_package_name Overrides the default PostgreSQL docs package name.
+# @param perl_package_name Overrides the default PostgreSQL Perl package name.
+# @param plperl_package_name Overrides the default PostgreSQL PL/Perl package name.
+# @param plpython_package_name Overrides the default PostgreSQL PL/Python package name.
+# @param python_package_name Overrides the default PostgreSQL Python package name.
+# @param postgis_package_name Overrides the default PostgreSQL PostGIS package name.     
+#
+# @param service_name Overrides the default PostgreSQL service name.
+# @param service_provider Overrides the default PostgreSQL service provider.
+# @param service_status Overrides the default status check command for your PostgreSQL service.
+# @param default_database Specifies the name of the default database to connect with.
 #
 # @param validcon_script_path     
 #
-# @param initdb_path              
-# @param createdb_path            
-# @param psql_path                
-# @param pg_hba_conf_path         
-# @param pg_ident_conf_path       
-# @param postgresql_conf_path     
-# @param recovery_conf_path       
+# @param initdb_path Path to the initdb command.
+# @param createdb_path Deprecated. Path to the createdb command.
+# @param psql_path Sets the path to the psql command.
+# @param pg_hba_conf_path Specifies the path to your pg_hba.conf file.
+# @param pg_ident_conf_path Specifies the path to your pg_ident.conf file.
+# @param postgresql_conf_path Sets the path to your postgresql.conf file.
+# @param recovery_conf_path Path to your recovery.conf file.
 # @param default_connect_settings
 #
-# @param pg_hba_conf_defaults     
+# @param pg_hba_conf_defaults Disables the defaults supplied with the module for pg_hba.conf if set to false. This is useful if you want to override the defaults. Be sure that your changes align with the rest of the module, as some access is required to perform some operations, such as basic psql operations.    
+#
+# @param datadir Overrides the default PostgreSQL data directory for the target platform.
+# 
+# @note Changing the datadir after installation causes the server to come to a full stop before making the change. For Red Hat systems, the data directory must be labeled appropriately for SELinux. On Ubuntu, you must explicitly set needs_initdb = true to allow Puppet to initialize the database in the new datadir (needs_initdb defaults to true on other systems).
+# @note Warning! If datadir is changed from the default, Puppet does not manage purging of the original data directory, which causes it to fail if the data directory is changed back to the original
+# 
+# @param confdir Overrides the default PostgreSQL configuration directory for the target platform.                  
+# @param bindir Overrides the default PostgreSQL binaries directory for the target platform.
+# @param xlogdir Overrides the default PostgreSQL xlog directory.                 
+# @param logdir Overrides the default PostgreSQL log directory.
+# @param log_line_prefix Overrides the default PostgreSQL log prefix.          
 #
-# @param datadir                  
-# @param confdir                  
-# @param bindir                   
-# @param xlogdir                  
-# @param logdir                   
-# @param log_line_prefix          
+# @param user Overrides the default PostgreSQL super user and owner of PostgreSQL related files in the file system.
+#  Default value: 'postgres'.                    
+# @param group Overrides the default postgres user group to be used for related files in the file system.
 #
-# @param user                     
-# @param group                    
+# @param version The version of PostgreSQL to install and manage.                 
+# @param postgis_version Defines the version of PostGIS to install, if you install PostGIS.         
+# @param repo_proxy Sets the proxy option for the official PostgreSQL yum-repositories only. This is useful if your server is behind a corporate firewall and needs to use proxy servers for outside connectivity.
+# Debian is currently not supported.              
 #
-# @param version                  
-# @param postgis_version          
-# @param repo_proxy               
-# @param repo_baseurl             
+# @param repo_baseurl Sets the baseurl for the PostgreSQL repository. Useful if you host your own mirror of the repository.
 #
-# @param needs_initdb             
+# @param needs_initdb Explicitly calls the initdb operation after the server package is installed and before the PostgreSQL service is started.            
 #
-# @param encoding                 
-# @param locale                   
-# @param data_checksums           
-# @param timezone                 
+# @param encoding Sets the default encoding for all databases created with this module. On certain operating systems, this is also used during the template1 initialization, so it becomes a default outside of the module as well.
+# @param locale Sets the default database locale for all databases created with this module. On certain operating systems, this is also used during the template1 initialization, so it becomes a default outside of the module as well.
+# @note On Debian, you'll need to ensure that the 'locales-all' package is installed for full functionality of PostgreSQL.
+# @param data_checksums 
+#   Boolean. Use checksums on data pages to help detect corruption by the I/O system that would otherwise be silent.
+#   Warning: This option is used during initialization by initdb, and cannot be changed later. If set, checksums are calculated for all objects, in all databases.
+#         
+# @param timezone Sets the default timezone of the postgresql server. The postgresql built-in default is taking the systems timezone information.
 #
 # @param manage_pg_hba_conf       
 # @param manage_pg_ident_conf     
 # @param manage_recovery_conf     
 #
-# @param manage_package_repo      
-# @param module_workdir           
+# @param manage_package_repo Sets up official PostgreSQL repositories on your host if set to true.
+# @param module_workdir Specifies working directory under which the psql command should be executed. May need to specify if '/tmp' is on volume mounted with noexec option.
 #
 #
 class postgresql::globals (

manifests/globals.pp

@@ -5,7 +5,7 @@
 # @param package_ensure
 #   String. Defaults to 'present'.
 # @param link_pg_config
-#   Boolean. 
+#   Boolean. If the bin directory used by the PostgreSQL page is not /usr/bin or /usr/local/bin, symlinks pg_config from the package's bin dir into usr/bin (not applicable to Debian systems). Set to false to disable this behavior.
 #
 #
 class postgresql::lib::devel(

manifests/lib/devel.pp

@@ -1,9 +1,12 @@
-# @summary This class installs the postgresql-docs
+# @summary Installs PostgreSQL bindings for Postgres-Docs. Set the following parameters if you have a custom version you would like to install.
+#
+# @note
+#   Make sure to add any necessary yum or apt repositories if specifying a custom version.
 #
 # @param package_name
-#   String.
+#   String. Specifies the name of the PostgreSQL docs package.
 # @param package_ensure
-#   String. Defaults to 'present'.
+#   Enum['present','absent']. Whether the PostgreSQL docs package resource should be present.
 # 
 #
 class postgresql::lib::docs (

manifests/lib/docs.pp

@@ -1,9 +1,12 @@
 # @summary This class installs the postgresql jdbc connector.
 #
+# @note
+#   Make sure to add any necessary yum or apt repositories if specifying a custom version.
+#
 # @param package_name
-#  String.
+#  String. Specifies the name of the PostgreSQL java package.
 # @param package_ensure
-#  String. Defaults to 'present'.
+#  Enum['present','absent']. Specifies whether the package is present.
 #
 class postgresql::lib::java (
   String $package_name      = $postgresql::params::java_package_name,

manifests/lib/java.pp

@@ -1,9 +1,9 @@
 # @summary This class installs the perl libs for postgresql.
 #
 # @param package_name
-#   String.
+#   String. Specifies the name of the PostgreSQL perl package to install.
 # @param package_ensure
-#   String. Defaults to 'present'.
+#   Enum['present','absent'].
 #
 class postgresql::lib::perl(
   String $package_name      = $postgresql::params::perl_package_name,

manifests/lib/perl.pp

@@ -1,9 +1,9 @@
 # @summary This class installs the python libs for postgresql.
 #
 # @param package_name
-#  String.
+#  String. The name of the PostgreSQL Python package.
 # @param package_ensure
-#  String. Defaults to 'present'.
+#  Enum['present','absent']
 #
 class postgresql::lib::python(
   String[1] $package_name   = $postgresql::params::python_package_name,

manifests/lib/python.pp

@@ -1,35 +1,43 @@
 # @summary This installs a PostgreSQL server
 #
-# @param postgres_password
-# @param package_name
-# @param package_ensure
+# @param postgres_password Sets the password for the postgres user to your specified value. By default, this setting uses the superuser account in the Postgres database, with a user called postgres and no password.
+# @param package_name Specifies the name of the package to use for installing the server software.
+# @param package_ensure Passes a value through to the package resource when creating the server instance.
 #
-# @param plperl_package_name
-# @param plpython_package_name
+# @param plperl_package_name Sets the default package name for the PL/Perl extension.
+# @param plpython_package_name Sets the default package name for the PL/Python extension.
 #
 # @param service_ensure
 # @param service_enable
-# @param service_manage
-# @param service_name
-# @param service_restart_on_change
-# @param service_provider
-# @param service_reload
-# @param service_status
-# @param default_database
-# @param default_connect_settings
+# @param service_manage Defines whether or not Puppet should manage the service.
+# @param service_name Overrides the default PostgreSQL service name.
+# @param service_restart_on_change Overrides the default behavior to restart your PostgreSQL service when a config entry has been changed that requires a service restart to become active.
+# @param service_provider Overrides the default PostgreSQL service provider.
+# @param service_reload Overrides the default reload command for your PostgreSQL service.
+# @param service_status Overrides the default status check command for your PostgreSQL service.
+# @param default_database Specifies the name of the default database to connect with. On most systems this is 'postgres'.
+# @param default_connect_settings Specifies a hash of environment variables used when connecting to a remote server. Becomes the default for other defined types, such as postgresql::server::role.
+#
 # @param listen_addresses
-# @param port
-# @param ip_mask_deny_postgres_user
-# @param ip_mask_allow_all_users
-# @param ipv4acls
-# @param ipv6acls
-#
-# @param initdb_path
-# @param createdb_path
-# @param psql_path
-# @param pg_hba_conf_path
-# @param pg_ident_conf_path
-# @param postgresql_conf_path
+# @param port Specifies the port for the PostgreSQL server to listen on. Note: The same port number is used for all IP addresses the server listens on. Also, for Red Hat systems and early Debian systems, changing the port causes the server to come to a full stop before being able to make the change.
+#   Default value: 5432. Meaning the Postgres server listens on TCP port 5432.
+#
+# @param ip_mask_deny_postgres_user Specifies the IP mask from which remote connections should be denied for the postgres superuser.
+#   Default value: '0.0.0.0/0', which denies any remote connection.
+#
+# @param ip_mask_allow_all_users Overrides PostgreSQL defaults for remote connections. By default, PostgreSQL does not allow database user accounts to connect via TCP from remote machines. If you'd like to allow this, you can override this setting.
+#   Set to '0.0.0.0/0' to allow database users to connect from any remote machine, or '192.168.0.0/1' to allow connections from any machine on your local '192.168' subnet.
+#   Default value: '127.0.0.1/32'.
+#
+# @param ipv4acls Lists strings for access control for connection method, users, databases, IPv4 addresses;
+# @param ipv6acls Lists strings for access control for connection method, users, databases, IPv6 addresses.
+#
+# @param initdb_path Specifies the path to the initdb command.
+# @param createdb_path Deprecated. Specifies the path to the createdb command.
+# @param psql_path Specifies the path to the psql command.
+# @param pg_hba_conf_path Specifies the path to your pg_hba.conf file.
+# @param pg_ident_conf_path Specifies the path to your pg_ident.conf file.
+# @param postgresql_conf_path Specifies the path to your postgresql.conf file.
 # @param recovery_conf_path
 #
 # @param datadir
@@ -38,26 +46,28 @@
 #
 # @param log_line_prefix
 #
-# @param pg_hba_conf_defaults
+# @param pg_hba_conf_defaults If false, disables the defaults supplied with the module for pg_hba.conf. This is useful if you disagree with the defaults and wish to override them yourself. Be sure that your changes of course align with the rest of the module, as some access is required to perform basic psql operations for example.
+#
+# @param user Overrides the default PostgreSQL super user and owner of PostgreSQL related files in the file system.
+# @param group Overrides the default postgres user group to be used for related files in the file system.
 #
-# @param user
-# @param group
+# @param needs_initdb Explicitly calls the initdb operation after server package is installed, and before the PostgreSQL service is started.
 #
-# @param needs_initdb
+# @param encoding Sets the default encoding for all databases created with this module. On certain operating systems this is also used during the template1 initialization, so it becomes a default outside of the module as well.
+# @param locale Sets the default database locale for all databases created with this module. On certain operating systems this is used during the template1 initialization as well, so it becomes a default outside of the module.
+# @param data_checksums Boolean. Use checksums on data pages to help detect corruption by the I/O system that would otherwise be silent.
+#   Warning: This option is used during initialization by initdb, and cannot be changed later. If set, checksums are calculated for all objects, in all databases.
 #
-# @param encoding
-# @param locale
-# @param data_checksums
 # @param timezone
 #
-# @param manage_pg_hba_conf
-# @param manage_pg_ident_conf
-# @param manage_recovery_conf
+# @param manage_pg_hba_conf Boolean. Whether to manage the pg_hba.conf.
+# @param manage_pg_ident_conf Boolean. Overwrites the pg_ident.conf file.
+# @param manage_recovery_conf Boolean. Specifies whether or not manage the recovery.conf.
 # @param module_workdir
 #
-# @param roles
-# @param config_entries
-# @param pg_hba_rules
+# @param roles Specifies a hash from which to generate postgresql::server::role resources.
+# @param config_entries Specifies a hash from which to generate postgresql::server::config_entry resources.
+# @param pg_hba_rules Specifies a hash from which to generate postgresql::server::pg_hba_rule resources.
 #
 # @param version
 #

manifests/server.pp

@@ -1,9 +1,8 @@
 # @summary Manage a postgresql.conf entry.
 #
-# @param ensure
-# @param value
+# @param ensure Removes an entry if set to 'absent'.
+# @param value Defines the value for the setting.
 # @param path
-#   Boolean. Defaults to false.
 #
 define postgresql::server::config_entry (
   $ensure = 'present',

manifests/server/config_entry.pp

@@ -1,9 +1,9 @@
 # @summary Install the contrib postgresql packaging.
 #
 # @param package_name
-#   String.
+#   String. The name of the PostgreSQL contrib package.
 # @param package_ensure
-#   String. Defaults to 'present'.
+#   Enum['present','absent']. Defaults to 'present'.
 # 
 #
 class postgresql::server::contrib (

manifests/server/contrib.pp

@@ -1,13 +1,13 @@
 # @summary Define for creating a database.
 #
 # @param comment 
-# @param dbname
-# @param owner
-# @param tablespace
-# @param template
-# @param encoding
-# @param locale
-# @param istemplate
+# @param dbname Sets the name of the database.
+# @param owner Sets name of the database owner.
+# @param tablespace Sets tablespace for where to create this database.
+# @param template Specifies the name of the template database from which to build this database. Default value: 'template0'.
+# @param encoding Overrides the character set during creation of the database.
+# @param locale Overrides the locale during creation of the database.
+# @param istemplate Defines the database as a template if set to true.
 # @param connect_settings
 #
 define postgresql::server::database(

manifests/server/database.pp

@@ -1,12 +1,12 @@
 # @summary Manage a database grant.
 #
-# @param privilege
-# @param db
-# @param role
-# @param ensure
-# @param psql_db
-# @param psql_user
-# @param connect_settings
+# @param privilege Specifies comma-separated list of privileges to grant. Valid options: 'ALL', 'CREATE', 'CONNECT', 'TEMPORARY', 'TEMP'.
+# @param db Specifies the database to which you are granting access.
+# @param role Specifies the role or user whom you are granting access to.
+# @param ensure Specifies whether to grant or revoke the privilege. Revoke or 'absent' works only in PostgreSQL version 9.1.24 or later.
+# @param psql_db Defines the database to execute the grant against. This should not ordinarily be changed from the default
+# @param psql_user Specifies the OS user for running psql. Default value: The default user for the module, usually 'postgres'.
+# @param connect_settings Specifies a hash of environment variables used when connecting to a remote server.
 #
 define postgresql::server::database_grant(
   $privilege,