add typedef and class documentation

manifests/acl.pp

@@ -1,3 +1,22 @@
+# @summary 
+#   Defines acl entries for a squid server.
+# @see
+#   http://www.squid-cache.org/Doc/config/acl/
+# @example create an ACL 'remote_urls' containing two entries
+#   squid::acl { 'remote_urls':
+#      type    => 'url_regex',
+#      entries => ['http://example.org/path',
+#                  'http://example.com/anotherpath'],
+#   }
+#
+# @param type 
+#   The acltype of the acl, must be defined, e.g url_regex, urlpath_regex, port, ..
+# @param aclname 
+#   The name of acl, defaults to the `title`.
+# @param entries 
+#   An array of acl entries, multiple members results in multiple lines in squid.conf.
+# @param order 
+#   Each ACL has an order `05` by default this can be specified if order of ACL definition matters.
 define squid::acl (
   String $type,
   String $aclname = $title,

manifests/auth_param.pp

@@ -1,3 +1,29 @@
+# @summary 
+#   Defines auth_param entries  for a squid server.
+# @see 
+#   http://www.squid-cache.org/Doc/config/auth_param/ 
+# @example
+#   squid::auth_param { 'basic auth_param':
+#     scheme  => 'basic',
+#     entries => [
+#       'program /usr/lib64/squid/basic_ncsa_auth /etc/squid/.htpasswd',
+#       'children 5',
+#       'realm Squid Basic Authentication',
+#       'credentialsttl 5 hours',
+#     ],
+#   }
+#   would result in multi entry squid auth_param:
+#   auth_param basic program /usr/lib64/squid/basic_ncsa_auth /etc/squid/.htpasswd
+#   auth_param basic children 5
+#   auth_param basic realm Squid Basic Authentication
+#   auth_param basic credentialsttl 5 hours
+# 
+# @param scheme 
+#   The scheme used for authentication must be defined. Valid values are 'basic', 'digest', 'negotiate' and 'ntlm'.
+# @param entries 
+#   An array of entries, multiple members results in multiple lines in squid.conf
+# @param order 
+#   Order can be used to configure where in `squid.conf`this configuration section should occur.
 define squid::auth_param (
   Enum['basic', 'digest', 'negotiate', 'ntlm']
           $scheme,

manifests/cache.pp

@@ -1,3 +1,22 @@
+# @summary 
+#   Defines cache entries  for a squid server.
+# @see 
+#   http://www.squid-cache.org/Doc/config/cache/
+# @example
+#   squid::cache { 'our_network_hosts_acl':
+#     action    => 'deny',
+#     comment   => 'Our networks hosts are denied for caching',
+#   }
+#
+#   Adds a squid.conf line:
+#   #Our networks hosts denied for caching
+#   cache deny our_network_hosts_acl
+# @param action
+#   Allow/deny caching for $title
+# @param comment
+#   Cache entry's preceding comment
+# @param order
+#   Order can be used to configure where in `squid.conf`this configuration section should occur.
 define squid::cache (
   Enum['allow', 'deny']
           $action  = 'allow',

manifests/cache_dir.pp

@@ -1,3 +1,35 @@
+# @summary 
+#   Defines cache_dir entries for a squid server.
+# @see
+#   http://www.squid-cache.org/Doc/config/cache_dir/ 
+# @example
+#   squid::cache_dir { '/data':
+#     type           => 'ufs',
+#     options        => '15000 32 256 min-size=32769',
+#     process_number => 2,
+#   }
+#   Results in the squid configuration of
+#
+#   if ${processor} = 2
+#   cache_dir ufs 15000 32 256 min-size=32769
+#   endif
+#
+# @param type 
+#   The type of cache, e.g ufs. defaults to `ufs`.
+# @param path 
+#   Defaults to the namevar, file path to  cache.
+# @param options 
+#   String of options for the cache. Defaults to empty string.
+# @param process_number 
+#   If specfied as an integer the cache will be wrapped
+#   in a `if $proceess_number` statement so the cache will be used by only
+#   one process. Default is undef.
+# @param manage_dir 
+#   If true puppet will attempt to create the
+#   directory, if false you will have to create it yourself. Make sure the
+#   directory has the correct owner, group and mode. Defaults to true.
+# @param order
+#   Order can be used to configure where in `squid.conf`this configuration section should occur.
 define squid::cache_dir (
   String            $type           = ufs,
   String            $path           = $title,

manifests/config.pp

@@ -1,3 +1,8 @@
+# @summary
+#   Configure the system to use squid
+#   config is included in the main class `squid`
+#   for parameters see `squid` class
+# @api private
 class squid::config (
   $config                        = $squid::config,
   $config_user                   = $squid::config_user,

manifests/extra_config_section.pp

@@ -1,3 +1,59 @@
+# @summary 
+#   The `extra_config_section` defiend type can be used for configuration directives that have not been exposed individually in this module.
+# 
+# @example Using a hash of config_entries:
+#   squid::extra_config_section { 'mail settings':
+#     order          => '60',
+#     config_entries => {
+#       'mail_from'    => '[email protected]',
+#       'mail_program' => 'mail',
+#     },
+#   }
+# 
+#   Results in a squid configuration of
+#   # mail settings
+#   mail_from [email protected]
+#   mail_program mail
+# 
+# @example Using an array of config_entries:
+#   squid::extra_config_section { 'ssl_bump settings':
+#     order          => '60',
+#     config_entries => {
+#       'ssl_bump'         => ['server-first', 'all'],
+#       'sslcrtd_program'  => ['/usr/lib64/squid/ssl_crtd', '-s', '/var/lib/ssl_db', '-M', '4MB'],
+#       'sslcrtd_children' => ['8', 'startup=1', 'idle=1'],
+#     }
+#   }
+# 
+#   Results in a squid configuration of:
+#   # ssl_bump settings
+#   ssl_bump server-first all
+#   sslcrtd_program /usr/lib64/squid/ssl_crtd -s /var/lib/ssl_db -M 4MB
+#   sslcrtd_children 8 startup=1 idle=1
+# 
+# @example Using an array of hashes of config_entries:
+#   squid::extra_config_section { 'always_directs':
+#     order          => '60',
+#     config_entries => [{
+#       'always_direct' => ['deny    www.reallyreallybadplace.com',
+#                           'allow   my-good-dst',
+#                           'allow   my-other-good-dst'],
+#     }],
+#   }
+# 
+#   Results in a squid configuration of
+#   # always_directs
+#   always_direct deny    www.reallyreallybadplace.com
+#   always_direct allow   my-good-dst
+#   always_direct allow   my-other-good-dst
+# 
+# @param comment 
+#   Defaults to the namevar and is used as a section comment in `squid.conf`.
+# @param config_entries 
+#   A hash of configuration entries to create in this section.  The hash key is the name of the configuration directive.  
+#   The value is either a string, or an array of strings to use as the configuration directive options.
+# @param order 
+#   Order can be used to configure where in `squid.conf` this configuration section should occur.
 define squid::extra_config_section (
   String              $comment = $title,
   Variant[Array,Hash] $config_entries = {},

manifests/http_access.pp

@@ -1,3 +1,33 @@
+# @summary 
+#   Defines http_access entries for a squid server.
+# @see 
+#   https://github.com/puppetlabs/puppetlabs-docker/blob/master/REFERENCE.md
+# @example
+#   squid::http_access { 'our_networks hosts':
+#     action => 'allow',
+#   }
+# 
+#   Adds a squid.conf line
+#   # http_access fragment for out_networks hosts
+#   http_access allow our_networks hosts
+# 
+# @example
+#   squid::http_access { 'our_networks hosts':
+#     action    => 'allow',
+#     comment   => 'Our networks hosts are allowed',
+#   }
+#
+#   Adds a squid.conf line
+#   # Our networks hosts are allowed
+#   http_access allow our_networks hosts
+# @param title
+#   The name of the ACL the rule is applied to
+# @param action
+#   allow or deny access for $title
+# @param order
+#   Order can be used to configure where in `squid.conf`this configuration section should occur.
+# @param comment
+#   http_access entry's preceding comment
 define squid::http_access (
   Enum['allow', 'deny']
           $action  = 'allow',

manifests/http_port.pp

@@ -1,3 +1,36 @@
+# @summary
+#   Defines http_port entries for a squid server.
+#   By setting optional `ssl` parameter to `true` will create https_port entries instead.
+# @see
+#   http://www.squid-cache.org/Doc/config/http_port/
+# @example
+#   squid::http_port { '10000':
+#     options => 'accel vhost'
+#   }
+#   squid::http_port { '10001':
+#     ssl     => true,
+#     options => 'cert=/etc/squid/ssl_cert/server.cert key=/etc/squid/ssl_cert/server.key'
+#   }
+#   squid::http_port { '127.0.0.1:3128':
+#   }
+#
+#   Results in a squid configuration of:
+#   http_port 10000 accel vhost
+#   https_port 10001 cert=/etc/squid/ssl_cert/server.cert key=/etc/squid/ssl_cert/server.key
+#   http_port 127.0.0.1:3128
+# @param title
+#   The title/namevar may be in the form `port` or `host:port` to provide the below values. Otherwise,
+#   specify `port` explicitly, and `host` if desired.
+# @param port 
+#   Defaults to the port of the namevar and is the port number to listen on.
+# @param host 
+#   Defaults to the host part of the namevar and is the interface to listen on. If not specified, Squid listens on all interfaces.
+# @param options 
+#   A string to specify any options for the default. By default and empty string.
+# @param ssl 
+#   When set to `true` creates https_port entries. Defaults to `false`.
+# @param order
+#   Order can be used to configure where in `squid.conf`this configuration section should occur.
 define squid::http_port (
   Optional[Stdlib::Port] $port    = undef,
   Optional[Stdlib::Host] $host    = undef,

manifests/https_port.pp

@@ -1,3 +1,13 @@
+# @summary 
+#   Defines https_port entries for a squid server. Results are the same with http_port and ssl set to `true`.
+# @see 
+#   http://www.squid-cache.org/Doc/config/https_port/
+# @param port 
+#   defaults to the namevar and is the port number.
+# @param options 
+#   A string to specify any options to add to the https_port line.  Defaults to an empty string.
+# @param order
+#   Order can be used to configure where in `squid.conf`this configuration section should occur.
 define squid::https_port (
   Variant[Pattern[/\d+/], Integer]
           $port    = $title,

manifests/icp_access.pp

@@ -1,3 +1,19 @@
+# @summary 
+#   Defines icp_access entries for a squid server.
+# @see http://www.squid-cache.org/Doc/config/icp_access/
+# @example
+#   squid::icp_access { 'our_networks hosts':
+#     action => 'allow',
+#   }
+#
+#   Adds a squid.conf line
+#   icp_access allow our_networks hosts
+#
+# @param action 
+#   Must be `deny` or `allow`. By default it is allow. The squid.conf file is ordered so by default
+#   all allows appear before all denys. This can be overidden with the `order` parameter.
+# @param order 
+#   Order can be used to configure where in `squid.conf`this configuration section should occur.
 define squid::icp_access (
   Enum['allow', 'deny']
           $action = 'allow',