add puppet-lint-param-docs

.sync.yml

@@ -0,0 +1,5 @@
+---
+Gemfile:
+  optional:
+    ':test':
+      - gem: puppet-lint-param-docs

Gemfile

@@ -8,6 +8,7 @@ group :test do
   gem 'coveralls',                  :require => false
   gem 'simplecov-console',          :require => false
   gem 'puppet_metadata', '~> 1.0',  :require => false
+  gem 'puppet-lint-param-docs',     :require => false
 end
 
 group :development do

REFERENCE.md

@@ -37,13 +37,13 @@
 
 ### Data types
 
-* [`Systemd::Dropin`](#systemddropin)
+* [`Systemd::Dropin`](#systemddropin): custom datatype that validates filenames/paths for valid systemd dropin files
 * [`Systemd::JournaldSettings`](#systemdjournaldsettings): Matches Systemd journald config Struct
-* [`Systemd::JournaldSettings::Ensure`](#systemdjournaldsettingsensure)
+* [`Systemd::JournaldSettings::Ensure`](#systemdjournaldsettingsensure): defines allowed ensure states for systemd-journald settings
 * [`Systemd::LogindSettings`](#systemdlogindsettings): Matches Systemd Login Manager Struct
-* [`Systemd::LogindSettings::Ensure`](#systemdlogindsettingsensure)
+* [`Systemd::LogindSettings::Ensure`](#systemdlogindsettingsensure): defines allowed ensure states for systemd-logind settings
 * [`Systemd::ServiceLimits`](#systemdservicelimits): Matches Systemd Service Limit Struct
-* [`Systemd::Unit`](#systemdunit)
+* [`Systemd::Unit`](#systemdunit): custom datatype that validates different filenames for systemd units
 
 ## Classes
 
@@ -328,19 +328,19 @@ where all networkd files are placed in
 
 Data type: `Boolean`
 
-
+when enabled, the different accounting options (network traffic, IO, CPU util...) are enabled for units
 
 ##### <a name="accounting"></a>`accounting`
 
 Data type: `Hash[String,String]`
 
-
+Hash of the different accounting options. This highly depends on the used systemd version. The module provides sane defaults.
 
 ##### <a name="purge_dropin_dirs"></a>`purge_dropin_dirs`
 
 Data type: `Boolean`
 
-
+When enabled, unused directories for dropin files will be purged
 
 ### <a name="systemdtmpfiles"></a>`systemd::tmpfiles`
 
@@ -379,7 +379,9 @@ Creates a drop-in file for a systemd unit
 
 The following parameters are available in the `systemd::dropin_file` defined type:
 
-* [`name`](#name)
+* [`unit`](#unit)
+* [`filename`](#filename)
+* [`ensure`](#ensure)
 * [`path`](#path)
 * [`selinux_ignore_defaults`](#selinux_ignore_defaults)
 * [`content`](#content)
@@ -390,16 +392,29 @@ The following parameters are available in the `systemd::dropin_file` defined typ
 * [`mode`](#mode)
 * [`show_diff`](#show_diff)
 * [`notify_service`](#notify_service)
-* [`unit`](#unit)
-* [`filename`](#filename)
-* [`ensure`](#ensure)
 
-##### <a name="name"></a>`name`
+##### <a name="unit"></a>`unit`
 
-Data type: `Pattern['^[^/]+\.conf$']`
+Data type: `Systemd::Unit`
+
+the The target unit file to create, the value will be set to the `filename` parameter as well
+
+##### <a name="filename"></a>`filename`
+
+Data type: `Systemd::Dropin`
 
 The target unit file to create
 
+Default value: `$name`
+
+##### <a name="ensure"></a>`ensure`
+
+Data type: `Enum['present', 'absent', 'file']`
+
+the state of this dropin file
+
+Default value: `'present'`
+
 ##### <a name="path"></a>`path`
 
 Data type: `Stdlib::Absolutepath`
@@ -420,29 +435,23 @@ Default value: ``false``
 
 Data type: `Optional[Variant[String,Sensitive[String]]]`
 
-The full content of the unit file
-
-* Mutually exclusive with ``$source``
+The full content of the unit file (Mutually exclusive with `$source`)
 
 Default value: ``undef``
 
 ##### <a name="source"></a>`source`
 
 Data type: `Optional[String]`
 
-The ``File`` resource compatible ``source``
-
-* Mutually exclusive with ``$content``
+The `File` resource compatible `source` Mutually exclusive with ``$content``
 
 Default value: ``undef``
 
 ##### <a name="target"></a>`target`
 
 Data type: `Optional[Stdlib::Absolutepath]`
 
-If set, will force the file to be a symlink to the given target
-
-* Mutually exclusive with both ``$source`` and ``$content``
+If set, will force the file to be a symlink to the given target (Mutually exclusive with both `$source` and `$content`
 
 Default value: ``undef``
 
@@ -486,28 +495,6 @@ Notify a service for the unit, if it exists
 
 Default value: ``false``
 
-##### <a name="unit"></a>`unit`
-
-Data type: `Systemd::Unit`
-
-
-
-##### <a name="filename"></a>`filename`
-
-Data type: `Systemd::Dropin`
-
-
-
-Default value: `$name`
-
-##### <a name="ensure"></a>`ensure`
-
-Data type: `Enum['present', 'absent', 'file']`
-
-
-
-Default value: `'present'`
-
 ### <a name="systemdnetwork"></a>`systemd::network`
 
 Creates network config for systemd-networkd
@@ -829,7 +816,7 @@ Default value: ``undef``
 
 Data type: `Enum['present', 'absent', 'file']`
 
-
+Defines the desired state of the timer
 
 Default value: `'present'`
 
@@ -844,20 +831,20 @@ Creates a systemd tmpfile
 
 The following parameters are available in the `systemd::tmpfile` defined type:
 
-* [`name`](#name)
+* [`filename`](#filename)
 * [`ensure`](#ensure)
 * [`path`](#path)
 * [`content`](#content)
 * [`source`](#source)
-* [`filename`](#filename)
 
-##### <a name="name"></a>`name`
+##### <a name="filename"></a>`filename`
 
-Data type: `Pattern['^[^/]+\.conf$']`
+Data type: `Systemd::Dropin`
 
-(filename)
 The name of the tmpfile to create
 
+Default value: `$name`
+
 ##### <a name="ensure"></a>`ensure`
 
 Data type: `Enum['present', 'absent', 'file']`
@@ -894,14 +881,6 @@ A ``File`` resource compatible ``source``
 
 Default value: ``undef``
 
-##### <a name="filename"></a>`filename`
-
-Data type: `Systemd::Dropin`
-
-
-
-Default value: `$name`
-
 ### <a name="systemdudevrule"></a>`systemd::udev::rule`
 
 Adds a custom udev rule
@@ -1137,7 +1116,7 @@ usually discover the appropriate provider for your platform.
 
 ### <a name="systemddropin"></a>`Systemd::Dropin`
 
-The Systemd::Dropin data type.
+custom datatype that validates filenames/paths for valid systemd dropin files
 
 Alias of
 
@@ -1188,7 +1167,7 @@ Struct[{
 
 ### <a name="systemdjournaldsettingsensure"></a>`Systemd::JournaldSettings::Ensure`
 
-The Systemd::JournaldSettings::Ensure data type.
+defines allowed ensure states for systemd-journald settings
 
 Alias of
 
@@ -1233,7 +1212,7 @@ Struct[{
 
 ### <a name="systemdlogindsettingsensure"></a>`Systemd::LogindSettings::Ensure`
 
-The Systemd::LogindSettings::Ensure data type.
+defines allowed ensure states for systemd-logind settings
 
 Alias of
 
@@ -1294,7 +1273,7 @@ Struct[{
 
 ### <a name="systemdunit"></a>`Systemd::Unit`
 
-The Systemd::Unit data type.
+custom datatype that validates different filenames for systemd units
 
 Alias of
 

lib/puppet/provider/loginctl_user/ruby.rb

@@ -1,4 +1,8 @@
+# @summary custom provider to manage systemd user sessions/linger
+# @see https://www.freedesktop.org/software/systemd/man/loginctl.html
+# @see https://wiki.archlinux.org/title/Systemd/User
 Puppet::Type.type(:loginctl_user).provide(:ruby) do
+  desc 'custom provider to manage systemd user sessions/linger'
   commands loginctl: 'loginctl'
 
   def self.instances

manifests/dropin_file.pp

@@ -4,44 +4,19 @@
 #
 # @see systemd.unit(5)
 #
-# @param name [Pattern['^[^/]+\.conf$']]
-#   The target unit file to create
-#
-# @param path
-#   The main systemd configuration path
-#
-# @param selinux_ignore_defaults
-#   If Puppet should ignore the default SELinux labels.
-#
-# @param content
-#   The full content of the unit file
-#
-#   * Mutually exclusive with ``$source``
-#
-# @param source
-#   The ``File`` resource compatible ``source``
-#
-#   * Mutually exclusive with ``$content``
-#
-# @param target
-#   If set, will force the file to be a symlink to the given target
-#
-#   * Mutually exclusive with both ``$source`` and ``$content``
-#
-# @param owner
-#   The owner to set on the dropin file
-#
-# @param group
-#   The group to set on the dropin file
-#
-# @param mode
-#   The mode to set on the dropin file
-#
-# @param show_diff
-#   Whether to show the diff when updating dropin file
-#
-# @param notify_service
-#   Notify a service for the unit, if it exists
+# @param unit the The target unit file to create, the value will be set to the `filename` parameter as well
+# @param filename The target unit file to create
+# @param ensure the state of this dropin file
+# @param path The main systemd configuration path
+# @param selinux_ignore_defaults If Puppet should ignore the default SELinux labels.
+# @param content The full content of the unit file (Mutually exclusive with `$source`)
+# @param source The `File` resource compatible `source` Mutually exclusive with ``$content``
+# @param target If set, will force the file to be a symlink to the given target (Mutually exclusive with both `$source` and `$content`
+# @param owner The owner to set on the dropin file
+# @param group The group to set on the dropin file
+# @param mode The mode to set on the dropin file
+# @param show_diff Whether to show the diff when updating dropin file
+# @param notify_service Notify a service for the unit, if it exists
 #
 define systemd::dropin_file (
   Systemd::Unit                               $unit,

manifests/init.pp

@@ -118,6 +118,16 @@
 #
 # @param network_path
 #   where all networkd files are placed in
+#
+# @param manage_accounting
+#   when enabled, the different accounting options (network traffic, IO, CPU util...) are enabled for units
+#
+# @param accounting
+#   Hash of the different accounting options. This highly depends on the used systemd version. The module provides sane defaults.
+#
+# @param purge_dropin_dirs
+#   When enabled, unused directories for dropin files will be purged
+#
 class systemd (
   Hash[String,Hash[String, Any]]                         $service_limits,
   Boolean                                                $manage_resolved,

manifests/timer.pp

@@ -55,6 +55,9 @@
 # @param enable
 #   If set, will manage the state of the unit.
 #
+# @param ensure
+#   Defines the desired state of the timer
+#
 define systemd::timer (
   Enum['present', 'absent', 'file']        $ensure = 'present',
   Stdlib::Absolutepath                     $path = '/etc/systemd/system',

manifests/tmpfile.pp

@@ -4,7 +4,7 @@
 #
 # @see systemd-tmpfiles(8)
 #
-# @param name [Pattern['^[^/]+\.conf$']] (filename)
+# @param filename
 #   The name of the tmpfile to create
 #
 # @param ensure

types/dropin.pp

@@ -1 +1,2 @@
+# @summary custom datatype that validates filenames/paths for valid systemd dropin files
 type Systemd::Dropin = Pattern['^[^/]+\.conf$']

types/journaldsettings/ensure.pp

@@ -1 +1,2 @@
+# @summary defines allowed ensure states for systemd-journald settings
 type Systemd::JournaldSettings::Ensure = Struct[{ 'ensure' => Enum['present','absent'] }]

types/logindsettings/ensure.pp

@@ -1 +1,2 @@
+# @summary defines allowed ensure states for systemd-logind settings
 type Systemd::LogindSettings::Ensure = Struct[{ 'ensure' => Enum['present','absent'] }]

types/unit.pp

@@ -1 +1,2 @@
+# @summary custom datatype that validates different filenames for systemd units
 type Systemd::Unit = Pattern['^[^/]+\.(service|socket|device|mount|automount|swap|target|path|timer|slice|scope)$']