Major update

.gitignore

@@ -1,9 +1,11 @@
 .librarian
 .tmp
 .vagrant
+.yardoc
 Gemfile.lock
 Puppetfile.lock
-spec/fixtures
+spec/fixtures/manifests
+spec/fixtures/modules
 pkg
 log
 coverage

.travis.yml

@@ -8,11 +8,7 @@ script: "bundle exec rake test"
 matrix:
   fast_finish: true
   include:
-  - rvm: 2.1.6
+  - rvm: 2.2.5
     env: PUPPET_GEM_VERSION="~> 4.0" STRICT_VARIABLES="yes"
-  - rvm: 2.1.5
-    env: PUPPET_GEM_VERSION="~> 3.0" FUTURE_PARSER="yes"
-  - rvm: 2.1.5
-    env: PUPPET_GEM_VERSION="~> 3.0"
 notifications:
-  email: false
+  email: true

Gemfile

@@ -8,7 +8,7 @@ group :development, :test do
   gem 'rspec-puppet', '>= 2.2.0',                         :require => false
   gem 'puppetlabs_spec_helper',                           :require => false
   gem 'metadata-json-lint',                               :require => false
-  gem 'puppet-lint', '>= 1.1.0',                          :require => false
+  gem 'puppet-lint', '>= 2.1.0',                          :require => false
   gem 'puppet-lint-unquoted_string-check',                :require => false
   gem 'puppet-lint-empty_string-check',                   :require => false
   gem 'puppet-lint-spaceship_operator_without_tag-check', :require => false
@@ -23,11 +23,13 @@ group :development, :test do
   gem 'puppet-lint-file_source_rights-check',             :require => false
   gem 'puppet-lint-alias-check',                          :require => false
   gem 'librarian-puppet',                                 :require => false
-  gem 'beaker', '>= 2.18.2', '< 3.0.0',                   :require => false
-  gem 'beaker-rspec',                                     :require => false
+  gem 'beaker', '>= 3.0.0',                               :require => false
+  gem 'beaker-rspec', '>= 6.0.0',                         :require => false
   gem 'rspec-puppet-facts', '>= 1.1.1',                   :require => false
   gem 'coveralls',                                        :require => false
   gem 'specinfra', '>= 2.42.1',                           :require => false
+  gem 'puppet-strings',                                   :require => false
+  gem 'beaker-puppet_install_helper',                     :require => false
 end
 
 if facterversion = ENV['FACTER_GEM_VERSION']

README.md

@@ -9,142 +9,72 @@ Tested with Travis CI
 
 #### Table of Contents
 
-1. [Overview](#overview)
-2. [Module Description - What the module does and why it is useful](#module-description)
-3. [Setup - The basics of getting started with oddjob](#setup)
+1. [Description](#description)
+2. [Setup - The basics of getting started with oddjob](#setup)
     * [What oddjob affects](#what-oddjob-affects)
     * [Beginning with oddjob](#beginning-with-oddjob)
-4. [Usage - Configuration options and additional functionality](#usage)
-    * [Classes and Defined Types](#classes-and-defined-types)
-        * [Class: oddjob](#class-oddjob)
-        * [Class: oddjob::mkhomedir](#class-oddjobmkhomedir)
-        * [Defined Type: oddjob::helper](#defined-type-oddjobhelper)
-    * [Examples](#examples)
-5. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
+3. [Usage - Configuration options and additional functionality](#usage)
+4. [Reference - An under-the-hood peek at what the module is doing and how](#reference)
 5. [Limitations - OS compatibility, etc.](#limitations)
 6. [Development - Guide for contributing to the module](#development)
 
-## Overview
+## Description
 
 This module manages oddjob, a D-Bus service which performs random tasks.
 
-## Module Description
-
-This module installs and manages the oddjob D-Bus service and the mkhomedir
-oddjob helper.
-
 ## Setup
 
 ### What oddjob affects
 
-* The package(s) containing the oddjob software.
-* The service controlling the oddjob daemon.
-* Configuration for adding oddjob to the D-Bus system bus.
+This module installs and manages the oddjob D-Bus service and the mkhomedir
+oddjob helper.
 
 ### Beginning with oddjob
 
+In the very simplest case, you can just include the following:
+
 ```puppet
 include ::dbus
 include ::oddjob
 ```
 
 ## Usage
 
-### Classes and Defined Types
-
-#### Class: `oddjob`
-
-**Parameters within `oddjob`:**
-
-##### `conf_dir`
-
-The configuration directory for helpers, usually `/etc/oddjob.conf.d`.
-
-##### `package_name`
-
-The name of the package to install that provides the oddjob software.
-
-##### `service_name`
-
-The name of the service managing the `oddjobd` daemon.
-
-#### Class: `oddjob::mkhomedir`
-
-**Parameters within `oddjob::mkhomedir`:**
-
-##### `package_name`
-
-The name of the package to install that provides the oddjob mkhomedir helper.
-
-#### Defined Type: `oddjob::helper`
-
-**Parameters within `oddjob::helper`:**
-
-##### `content`
-
-The contents of the oddjob helper configuration file.
-
-##### `dbus_content`
-
-The optional contents of a D-Bus system bus configuration file.
-
-##### `name`
-
-The name will be used to construct the filename for the helper configuration
-file of the form `${conf_dir}/oddjobd-${name}.conf`. If a D-Bus system bus
-configuration file is desired the filename will be of the form
-`oddjob-${name}.conf` usually under `/etc/dbus-1/system.d`.
-
-### Examples
-
-To install and enable the mkhomedir oddjob helper:
+To install the mkhomedir Oddjob job:
 
 ```puppet
 include ::dbus
 include ::oddjob
 include ::oddjob::mkhomedir
 ```
 
-It's then necessary to enable the `pam_oddjob_mkhomedir.so` PAM module somehow,
-which can require `Class['::oddjob::mkhomedir']` as a dependency.
+You will then likely want to configure the PAM stack to utilise this.
 
 ## Reference
 
-### Classes
-
-#### Public Classes
-
-* [`oddjob`](#class-oddjob): Main class for installing the oddjob software.
-* [`oddjob::mkhomedir`](#class-oddjobmkhomedir): Main class for installing the
-  mkhomedir oddjob helper.
-
-#### Private Classes
-
-* `oddjob::config`: Handles oddjob configuration.
-* `oddjob::install`: Handles oddjob installation.
-* `oddjob::params`: Different configuration data for different systems.
-* `oddjob::service`: Handles starting the oddjobd daemon.
-* `oddjob::mkhomedir::config`: Handles mkhomedir oddjob helper configuration.
-* `oddjob::mkhomedir::install`: Handles mkhomedir oddjob helper installation.
-
-### Defined Types
-
-#### Public Defined Types
-
-* [`oddjob::helper`](#defined-type-oddjobhelper): Installs per-helper
-  configuration and optionally D-Bus system bus configuration.
+The reference documentation is generated with
+[puppet-strings](https://github.com/puppetlabs/puppet-strings) and the latest
+version of the documentation is hosted at
+[https://bodgit.github.io/puppet-oddjob/](https://bodgit.github.io/puppet-oddjob/).
 
 ## Limitations
 
-This module has been built on and tested against Puppet 3.0 and higher.
+This module has been built on and tested against Puppet 4.4.0 and higher.
 
 The module has been tested on:
 
-* RedHat/CentOS Enterprise Linux 6/7
-
-Testing on other platforms has been light and cannot be guaranteed.
+* RedHat Enterprise Linux 6/7
 
 ## Development
 
+The module has both [rspec-puppet](http://rspec-puppet.com) and
+[beaker-rspec](https://github.com/puppetlabs/beaker-rspec) tests. Run them
+with:
+
+```
+$ bundle exec rake test
+$ PUPPET_INSTALL_TYPE=agent PUPPET_INSTALL_VERSION=x.y.z bundle exec rake beaker:<nodeset>
+```
+
 Please log issues or pull requests at
 [github](https://github.com/bodgit/puppet-oddjob).

Rakefile

@@ -1,6 +1,8 @@
 require 'puppetlabs_spec_helper/rake_tasks'
 require 'puppet-lint/tasks/puppet-lint'
 require 'rake/clean'
+require 'metadata-json-lint/rake_task'
+require 'puppet-strings/tasks'
 
 CLEAN.include('spec/fixtures/manifests', 'spec/fixtures/modules')
 CLOBBER.include('.tmp', '.librarian', '.vagrant', 'Puppetfile.lock', 'log', 'junit', 'coverage')
@@ -23,7 +25,7 @@ task :test => [
   'lint',
 ]
 
-PuppetLint.configuration.log_format = '%{path}:%{linenumber}:%{check}:%{KIND}:%{message}'
+PuppetLint.configuration.log_format = '%{path}:%{line}:%{check}:%{KIND}:%{message}'
 PuppetLint.configuration.ignore_paths = ['pkg/**/*.pp', 'spec/**/*.pp', 'vendor/**/*.pp']
 PuppetLint.configuration.fail_on_warnings = true
 PuppetLint.configuration.relative = true

manifests/config.pp

@@ -1,8 +1,8 @@
-#
+# @!visibility private
 class oddjob::config {
 
   ::dbus::system { 'oddjob':
-    content => file('oddjob/oddjob.conf'),
+    content => file("${module_name}/oddjob.conf"),
   }
 
   # FIXME Needed?
@@ -18,7 +18,7 @@
     owner   => 0,
     group   => 0,
     mode    => '0644',
-    content => file('oddjob/oddjobd.conf'),
+    content => file("${module_name}/oddjobd.conf"),
   }
 
   file { $::oddjob::conf_dir:
@@ -29,6 +29,6 @@
   }
 
   ::oddjob::helper { 'introspection':
-    content => file('oddjob/oddjobd-introspection.conf'),
+    content => file("${module_name}/oddjobd-introspection.conf"),
   }
 }

manifests/helper.pp

@@ -1,23 +1,35 @@
+# Helper to configure Oddjob jobs.
 #
+# @example
+#   include ::dbus
+#   include ::oddjob
+#   ::oddjob::helper { 'mkhomedir':
+#     content      => file('oddjob/oddjobd-mkhomedir.conf'),
+#     dbus_content => file('oddjob/oddjob-mkhomedir.conf'),
+#   }
+#
+# @param content The Oddjob job content.
+# @param dbus_content The D-Bus configuration content.
+# @param job The name of the Oddjob job.
+#
+# @see puppet_classes::oddjob ::oddjob
 define oddjob::helper (
-  $content,
-  $dbus_content = undef,
+  String           $content,
+  Optional[String] $dbus_content = undef,
+  String           $job          = $title,
 ) {
 
   if ! defined(Class['::oddjob']) {
     fail('You must include the oddjob base class before using any oddjob defined resources')
   }
 
-  validate_string($content)
-  validate_string($dbus_content)
-
   if $dbus_content {
-    ::dbus::system { "oddjob-${name}":
+    ::dbus::system { "oddjob-${job}":
       content => $dbus_content,
     }
   }
 
-  file { "${::oddjob::conf_dir}/oddjobd-${name}.conf":
+  file { "${::oddjob::conf_dir}/oddjobd-${job}.conf":
     ensure  => file,
     owner   => 0,
     group   => 0,

manifests/init.pp

@@ -1,22 +1,26 @@
+# Installs and manages Oddjob.
 #
+# @example Declaring the class
+#   include ::dbus
+#   include ::oddjob
+#
+# @param conf_dir Top-level configuration directory, usually
+#   `/etc/oddjobd.conf.d`.
+# @param package_name The name of the package.
+# @param service_name The service name.
+#
+# @see puppet_classes::oddjob::mkhomedir ::oddjob::mkhomedir
+# @see puppet_defined_types::oddjob::helper ::oddjob::helper
 class oddjob (
-  $conf_dir     = $::oddjob::params::conf_dir,
-  $package_name = $::oddjob::params::package_name,
-  $service_name = $::oddjob::params::service_name,
+  Stdlib::Absolutepath $conf_dir     = $::oddjob::params::conf_dir,
+  String               $package_name = $::oddjob::params::package_name,
+  String               $service_name = $::oddjob::params::service_name,
 ) inherits ::oddjob::params {
 
-  validate_absolute_path($conf_dir)
-  validate_string($package_name)
-  validate_string($service_name)
-
-  include ::oddjob::install
-  include ::oddjob::config
-  include ::oddjob::service
-
-  anchor { 'oddjob::begin': }
-  anchor { 'oddjob::end': }
+  contain ::oddjob::install
+  contain ::oddjob::config
+  contain ::oddjob::service
 
-  Anchor['oddjob::begin'] -> Class['::oddjob::install']
-    -> Class['::oddjob::config'] ~> Class['::oddjob::service']
-    -> Anchor['oddjob::end']
+  Class['::oddjob::install'] -> Class['::oddjob::config']
+    ~> Class['::oddjob::service']
 }

manifests/install.pp

@@ -1,4 +1,4 @@
-#
+# @!visibility private
 class oddjob::install {
 
   package { $::oddjob::package_name:

manifests/mkhomedir.pp

@@ -1,20 +1,23 @@
+# Installs the Oddjob mkhomedir job.
 #
+# @example Declaring the class
+#   include ::dbus
+#   include ::oddjob
+#   include ::oddjob::mkhomedir
+#
+# @param package_name The name of the package.
+#
+# @see puppet_classes::oddjob ::oddjob
 class oddjob::mkhomedir (
-  $package_name = $::oddjob::params::mkhomedir_package_name,
+  String $package_name = $::oddjob::params::mkhomedir_package_name,
 ) inherits ::oddjob::params {
 
   if ! defined(Class['::oddjob']) {
     fail('You must include the oddjob base class before using the oddjob::mkhomedir class')
   }
 
-  validate_string($package_name)
-
-  include ::oddjob::mkhomedir::install
-  include ::oddjob::mkhomedir::config
-
-  anchor { 'oddjob::mkhomedir::begin': }
-  anchor { 'oddjob::mkhomedir::end': }
+  contain ::oddjob::mkhomedir::install
+  contain ::oddjob::mkhomedir::config
 
-  Anchor['oddjob::mkhomedir::begin'] -> Class['::oddjob::mkhomedir::install']
-    -> Class['::oddjob::mkhomedir::config'] -> Anchor['oddjob::mkhomedir::end']
+  Class['::oddjob::mkhomedir::install'] -> Class['::oddjob::mkhomedir::config']
 }