warn for examples without description/title

[bastelfreak]

let's say we have this:

# @summary This type creates multiple cron jobs via a single file in /etc/cron.d/
# @param jobs A hash of multiple cron jobs using the same structure as cron::job and using the same defaults for each parameter.
# @param ensure The state to ensure this resource exists in. Can be absent, present.
# @param environment An array of environment variable settings.
# @param mode The mode to set on the created job file.
#
# @example
#  cron::job::multiple { 'test':
#    jobs => [
#      {
#        minute      => '55',
#        hour        => '5',
#        date        => '*',
#        month       => '*',
#        weekday     => '*',
#        user        => 'rmueller',
#        command     => '/usr/bin/uname',
#      },
#      {
#        command     => '/usr/bin/sleep 1',
#      },
#      {
#        command     => '/usr/bin/sleep 10',
#        special     => 'reboot',
#      },
#    ],
#    environment => [ 'PATH="/usr/sbin:/usr/bin:/sbin:/bin"' ],
#  }

puppet-strings will render this, but will add ### in the middle of nowhere. It expects that each example has a title like this:

# @example create multiple cron jobs at once
#  cron::job::multiple { 'test':
#    jobs => [
#      {
#        minute      => '55',
#        hour        => '5',
#        date        => '*',
#        month       => '*',
#        weekday     => '*',
#        user        => 'rmueller',
#        command     => '/usr/bin/uname',
#      },
#      {
#        command     => '/usr/bin/sleep 1',
#      },
#      {
#        command     => '/usr/bin/sleep 10',
#        special     => 'reboot',
#      },
#    ],
#    environment => [ 'PATH="/usr/sbin:/usr/bin:/sbin:/bin"' ],
#  }

I think this plugin should warn about such missing titles.

[ekohl]

I've been wondering about that. Perhaps we actually need to actually run puppet-strings on a class and verify the parsed data. That will provide the best guarantee.

Having said that, perhaps puppet-strings itself could issue a warning and have a mode where warnings are fatal.

[bastelfreak]

I raised puppetlabs/puppet-strings#290