Use puppet-strings comments

Fix comments to rely on puppet-strings comments format for documentation
and generate `REFERENCE.md`.

lib/puppet/provider/cert_file/posix.rb

@@ -3,6 +3,8 @@
 require 'pp'
 
 Puppet::Type.type(:cert_file).provide :posix do
+  desc 'POSIX provider for certificate files'
+
   confine feature: :posix
 
   def exists?

lib/puppet/type/cert_file.rb

@@ -22,6 +22,7 @@
   end
 
   newparam(:source) do
+    desc 'The source file'
     validate do |source|
       begin
         uri = URI.parse(Puppet::Util.uri_encode(source))

lib/puppet/type/dhparam.rb

@@ -7,6 +7,7 @@
   ensurable
 
   newparam(:path, namevar: true) do
+    desc 'The path of the file'
     validate do |value|
       path = Pathname.new(value)
       raise ArgumentError, "Path must be absolute: #{path}" unless path.absolute?

lib/puppet/type/x509_request.rb

@@ -7,6 +7,7 @@
   ensurable
 
   newparam(:path, namevar: true) do
+    desc 'The path of the certificate signing request'
     validate do |value|
       path = Pathname.new(value)
       raise ArgumentError, "Path must be absolute: #{path}" unless path.absolute?
@@ -24,6 +25,7 @@
   end
 
   newparam(:template) do
+    desc 'The template to use'
     defaultto do
       path = Pathname.new(@resource[:path])
       "#{path.dirname}/#{path.basename(path.extname)}.cnf"
@@ -35,6 +37,7 @@
   end
 
   newparam(:private_key) do
+    desc 'The path of the private key'
     defaultto do
       path = Pathname.new(@resource[:path])
       "#{path.dirname}/#{path.basename(path.extname)}.key"

manifests/certificate/x509.pp

@@ -1,68 +1,96 @@
-# == Definition: openssl::certificate::x509
+# @summary Creates a certificate, key and CSR according to datas provided.
 #
-# Creates a certificate, key and CSR according to datas provided.
+# @param ensure
+#   ensure wether certif and its config are present or not
+# @param country
+#   certificate countryName
+# @param state
+#   certificate stateOrProvinceName
+# @param locality
+#   certificate localityName
+# @param commonname
+#   certificate CommonName
+# @param altnames
+#   certificate subjectAltName.
+#   Can be an array or a single string.
+# @param extkeyusage
+#   certificate extended key usage
+#   Value           | Meaning
+#   ----------------|-------------------------------------
+#   serverAuth      | SSL/TLS Web Server Authentication.
+#   clientAuth      | SL/TLS Web Client Authentication.
+#   codeSigning     | Code signing.
+#   emailProtection | E-mail Protection (S/MIME).
+#   timeStamping    | Trusted Timestamping
+#   OCSPSigning     | OCSP Signing
+#   ipsecIKE        | ipsec Internet Key Exchange
+#   msCodeInd       | Microsoft Individual Code Signing (authenticode)
+#   msCodeCom       | Microsoft Commercial Code Signing (authenticode)
+#   msCTLSign       | Microsoft Trust List Signing
+#   msEFS           | Microsoft Encrypted File System
 #
-# === Parameters
-#  [*ensure*]         ensure wether certif and its config are present or not
-#  [*country*]        certificate countryName
-#  [*state*]          certificate stateOrProvinceName
-#  [*locality*]       certificate localityName
-#  [*commonname*]     certificate CommonName
-#  [*altnames*]       certificate subjectAltName.
-#                     Can be an array or a single string.
-#  [*extkeyusage*]    certificate extended key usage
-#  # Value            Meaning
-#  -----              -------
-#  serverAuth         SSL/TLS Web Server Authentication.
-#  clientAuth         SL/TLS Web Client Authentication.
-#  codeSigning        Code signing.
-#  emailProtection    E-mail Protection (S/MIME).
-#  timeStamping       Trusted Timestamping
-#  OCSPSigning        OCSP Signing
-#  ipsecIKE           ipsec Internet Key Exchange
-#  msCodeInd          Microsoft Individual Code Signing (authenticode)
-#  msCodeCom          Microsoft Commercial Code Signing (authenticode)
-#  msCTLSign          Microsoft Trust List Signing
-#  msEFS              Microsoft Encrypted File System
+# @param organization
+#   certificate organizationName
+# @param unit
+#   certificate organizationalUnitName
+# @param email
+#   certificate emailAddress
+# @param days
+#   certificate validity
+# @param base_dir
+#   where cnf, crt, csr and key should be placed.
+#   Directory must exist
+# @param key_size
+#   Size of the key to generate.
+# @param owner
+#   cnf, crt, csr and key owner. User must exist
+# @param group
+#   cnf, crt, csr and key group. Group must exist
+# @param key_owner
+#   key owner. User must exist. defaults to $owner
+# @param key_group
+#   key group. Group must exist. defaults to $group
+# @param key_mode
+#   key group.
+# @param password
+#   private key password. undef means no passphrase
+#   will be used to encrypt private key.
+# @param force
+#   whether to override certificate and request
+#   if private key changes
+# @param cnf_tpl
+#   Specify an other template to generate ".cnf" file.
+# @param cnf_dir
+#   where cnf should be placed.
+#   Directory must exist, defaults to $base_dir.
+# @param crt_dir
+#   where crt should be placed.
+#   Directory must exist, defaults to $base_dir.
+# @param csr_dir
+#   where csr should be placed.
+#   Directory must exist, defaults to $base_dir.
+# @param key_dir
+#   where key should be placed.
+#   Directory must exist, defaults to $base_dir.
+# @param cnf
+#   override cnf path entirely.
+#   Directory must exist, defaults to $cnf_dir/$title.cnf
+# @param crt
+#   override crt path entirely.
+#   Directory must exist, defaults to $crt_dir/$title.crt
+# @param csr
+#   override csr path entirely.
+#   Directory must exist, defaults to $csr_dir/$title.csr
+# @param key
+#   override key path entirely.
+#   Directory must exist, defaults to $key_dir/$title.key
+# @param encrypted
+#   Flag requesting the exported key to be unencrypted by
+#   specifying the -nodes option during the CSR generation. Turning
+#   off encryption is needed by some applications, such as OpenLDAP.
+#   Defaults to true (key is encrypted)
 #
-#  [*organization*]   certificate organizationName
-#  [*unit*]           certificate organizationalUnitName
-#  [*email*]          certificate emailAddress
-#  [*days*]           certificate validity
-#  [*base_dir*]       where cnf, crt, csr and key should be placed.
-#                     Directory must exist
-#  [*owner*]          cnf, crt, csr and key owner. User must exist
-#  [*group*]          cnf, crt, csr and key group. Group must exist
-#  [*key_owner*]      key owner. User must exist. defaults to $owner
-#  [*key_group*]      key group. Group must exist. defaults to $group
-#  [*key_mode*]       key group.
-#  [*password*]       private key password. undef means no passphrase
-#                     will be used to encrypt private key.
-#  [*force*]          whether to override certificate and request
-#                     if private key changes
-#  [*cnf_tpl*]        Specify an other template to generate ".cnf" file.
-#  [*cnf_dir*]        where cnf should be placed.
-#                     Directory must exist, defaults to $base_dir.
-#  [*crt_dir*]        where crt should be placed.
-#                     Directory must exist, defaults to $base_dir.
-#  [*csr_dir*]        where csr should be placed.
-#                     Directory must exist, defaults to $base_dir.
-#  [*key_dir*]        where key should be placed.
-#                     Directory must exist, defaults to $base_dir.
-#  [*cnf*]            override cnf path entirely.
-#                     Directory must exist, defaults to $cnf_dir/$title.cnf
-#  [*crt*]            override crt path entirely.
-#                     Directory must exist, defaults to $crt_dir/$title.crt
-#  [*csr*]            override csr path entirely.
-#                     Directory must exist, defaults to $csr_dir/$title.csr
-#  [*key*]            override key path entirely.
-#                     Directory must exist, defaults to $key_dir/$title.key
-#  [*encrypted*]      Flag requesting the exported key to be unencrypted by
-#                     specifying the -nodes option during the CSR generation. Turning
-#                     off encryption is needed by some applications, such as OpenLDAP.
-#                     Defaults to true (key is encrypted)
-#
-# === Example
+# @example basic usage
 #
 #   openssl::certificate::x509 { 'foo.bar':
 #     ensure       => present,
@@ -73,19 +101,15 @@
 #     owner        => 'www-data',
 #   }
 #
-# This will create files "foo.bar.cnf", "foo.bar.crt", "foo.bar.key"
-# and "foo.bar.csr" in /var/www/ssl/.
-# All files will belong to user "www-data".
-#
-# Those files can be used as is for apache, openldap and so on.
-#
-# If you wish to ensure a key is read-only to a process:
-# set $key_group to match the group of the process,
-# and set $key_mode to '0640'.
+#   This will create files "foo.bar.cnf", "foo.bar.crt", "foo.bar.key"
+#   and "foo.bar.csr" in /var/www/ssl/.
+#   All files will belong to user "www-data".
 #
-# === Requires
+#   Those files can be used as is for apache, openldap and so on.
 #
-#   - `puppetlabs/stdlib`
+#   If you wish to ensure a key is read-only to a process:
+#   set $key_group to match the group of the process,
+#   and set $key_mode to '0640'.
 #
 define openssl::certificate::x509 (
   String                             $country,

manifests/certificates.pp

@@ -1,12 +1,8 @@
-# == Class: openssl::certificates
+# @summary Generates x509 certificates based on class parameters
 #
-# Generates x509 certificates based on class parameters
-#
-# === Parameters
-#  [*x509_certs*]
-#
-# === Example
+# @param x509_certs
 #
+# @example basic usage
 #   class { '::openssl::certificate':
 #     x509_certs => { '/path/to/certificate.crt' => {  ensure      => 'present',
 #                                                      password    => 'j(D$',

manifests/configs.pp

@@ -1,46 +1,42 @@
-# == Class: openssl::configs
+# @summary Generates openssl.conf files using defaults
 #
-# Generates openssl.conf files using defaults
-#
-# === Parameters
-# [*owner*]
+# @param owner
 #   default owner for the configuration files
-# [*group*]
+# @param group
 #   default group for the configuration files
-# [*mode*]
+# @param mode
 #   default mode for the configuration files
-# [*country*]
+# @param country
 #   default value for country
-# [*state*]
+# @param state
 #   default value for state
-# [*locality*]
+# @param locality
 #   default value for locality
-# [*organization*]
+# @param organization
 #   default value for organization
-# [*unit*]
+# @param unit
 #   default value for unit
-# [*email*]
+# @param email
 #   default value for email
-# [*default_bits*]
+# @param default_bits
 #   default key size to generate
-# [*default_md*]
+# @param default_md
 #   default message digest to use
-# [*default_keyfile*]
+# @param default_keyfile
 #   default name for the keyfile
-# [*basicconstraints*]
+# @param basicconstraints
 #   version 3 certificate extension basic constraints
-# [*extendedkeyusages*]
+# @param extendedkeyusages
 #   version 3 certificate extension extended key usage
-# [*keyusages*]
+# @param keyusages
 #   version 3 certificate extension key usage
-# [*subjectaltnames*]
+# @param subjectaltnames
 #   version 3 certificate extension for alternative names
 #   currently supported are IP (v4) and DNS
-# [*conffiles*]
+# @param conffiles
 #   config files to generate
 #
-# === Example
-#
+# @example basic usage
 #   class { '::openssl::configs':
 #     conffiles => { '/path/to/openssl.conf' => { ensure     => 'present',
 #                                                 commonname => 'somewhere.org',},

manifests/dhparam.pp

@@ -1,19 +1,19 @@
-# == Definition: openssl::dhparam
-#
-# Creates Diffie Helman parameters.
-#
-# === Parameters
-#  [*path*]    path to write DH parameters to
-#  [*ensure*]  ensure whether DH paramers file is present or absent
-#  [*size*]    number of bits for the parameter set
-#  [*owner*]   file owner. User must exist
-#  [*group*]   file group. Group must exist
-#  [*mode*]    file mode.
-#
-# === Requires
-#
-#   - `puppetlabs/stdlib`
+# @summary Creates Diffie Helman parameters.
 #
+# @param path
+#   path to write DH parameters to
+# @param ensure
+#   ensure whether DH paramers file is present or absent
+# @param size
+#   number of bits for the parameter set
+# @param owner
+#   file owner. User must exist
+# @param group
+#   file group. Group must exist
+# @param mode
+#   file mode.
+# @param fastmode
+#   Use "fastmode" for dhparam generation
 define openssl::dhparam (
   Stdlib::Absolutepath      $path = $name,
   Enum['present', 'absent'] $ensure = present,

manifests/export/pem_cert.pp

@@ -1,12 +1,15 @@
-# == Definition: openssl::export::pem_cert
+# @summary Export certificate(s) to PEM/x509 format
 #
-# Export certificate(s) to PEM/x509 format
-#
-# == Parameters
-#   [*pfx_cert*]  - PFX certificate/key container
-#   [*der_cert*]  - DER certificate
-#   [*pem_cert*]  - PEM/x509 certificate
-#   [*in_pass*]   - PFX password
+# @param ensure
+#   Whether the certificate file should exist
+# @param pfx_cert
+#   PFX certificate/key container
+# @param der_cert
+#   DER certificate
+# @param pem_cert
+#   PEM/x509 certificate
+# @param in_pass
+#   PFX password
 #
 define openssl::export::pem_cert (
   Enum['present', 'absent']       $ensure   = present,

manifests/export/pem_key.pp

@@ -1,12 +1,15 @@
-# == Definition: openssl::export::pem_key
+# @summary Export a key to PEM format
 #
-# Export a key to PEM format
-#
-# == Parameters
-#   [*pfx_cert*]  - PFX certificate/key container
-#   [*pem_key*]   - PEM certificate
-#   [*in_pass*]   - PFX container password
-#   [*out_pass*]  - PEM key password
+# @param pfx_cert
+#   PFX certificate/key container
+# @param pem_key
+#   PEM certificate
+# @param ensure
+#   Whether the key file should exist
+# @param in_pass
+#   PFX container password
+# @param out_pass
+#   PEM key password
 #
 define openssl::export::pem_key (
   Stdlib::Absolutepath      $pfx_cert,