puppet-strings 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8e021936451f50bd6d90032ebb46117245b1be028c0e717a02bb54ceb682194
-  data.tar.gz: 2ae779863af3e9882d2d5c6a0609cfb4fd994a2683429a9f62a271762e58828d
+  metadata.gz: 9bfc095b6c7aa9124cfa44c79aa0404361fbe9b3971e58495aa8354f1b84163a
+  data.tar.gz: 56c425e69b8bd4b1e9c6a0bb07a25ca806d880e6e9a865afa8137d12b5412442
 SHA512:
-  metadata.gz: 4795376753de54d5157d4b040781e9b2c322a777efa62b0400968ec895cb6a5aba32c20d19c374f9a5ab4c06b6fdcf6256f9c722684b356f1b64907194487f22
-  data.tar.gz: 564f9d8ec0b7db59f46c882358c3126ad7d98f9629c4760f96b496f94563af69f69dcc0560fcb6465c88c0104aca6dd8d1df2342740b626a3c3e9fc80f3b90a3
+  metadata.gz: 0a0fcbc8af4653fb35166cad42488f21bf5f046092ef1434331c7d4ba03fa4ac2544c3e220859c9dc2de94b4a263caed7b35a6185df297bf6dbb631553601f9d
+  data.tar.gz: 7cf9f63f1fd50af678f4b3891ed7ac9da3d5eda249de6df50dd10ac93eed078f1f7fab6b5ca6945e6e057e89ce55c227b4aba1aab84884e6d89b1f039677ed38

data/CHANGELOG.md

@@ -3,6 +3,16 @@
 All significant changes to this repo will be summarized in this file.
 
 
+## [v2.4.0](https://github.com/puppetlabs/puppet-strings/tree/v2.4.0) (2020-02-18)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.1...v2.4.0)
+
+Added
+
+- Add missing HTML output support for enum tag [\#218](https://github.com/puppetlabs/puppet-strings/pull/218) ([seanmil](https://github.com/seanmil))
+- \(PDOC-295\) Add @enum tag support for Enum data types [\#215](https://github.com/puppetlabs/puppet-strings/pull/215) ([seanmil](https://github.com/seanmil))
+- Expanded default search glob for plans. [\#214](https://github.com/puppetlabs/puppet-strings/pull/214) ([Raskil](https://github.com/Raskil))
+
 ## [v2.3.1](https://github.com/puppetlabs/puppet-strings/tree/v2.3.1) (2019-09-23)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.0...v2.3.1)

data/CONTRIBUTING.md

@@ -7,13 +7,44 @@ that we can have a chance of keeping on top of things.
 
 ## Getting Started
 
-* Make sure you have a [Jira account](http://tickets.puppetlabs.com)
 * Make sure you have a [GitHub account](https://github.com/signup/free)
 * Submit a ticket for your issue, assuming one does not already exist.
   * Clearly describe the issue including steps to reproduce when it is a bug.
   * Make sure you fill in the earliest version that you know has the issue.
 * Fork the repository on GitHub
 
+## Submit an issue
+
+We use GitHub Issues for issue tracking on puppet-strings.
+
+Before you submit your issue, take a minute to...
+
+1. **Use the GitHub issue search** — check if the issue has already been
+   reported.
+
+2. **Check if the issue has been fixed** — try to reproduce it using the
+   latest `master` or release tag.
+
+A good bug report shouldn't leave others needing to chase you up for more
+information. Please try to be as **detailed as possible** in your issue. What is
+your environment? What steps will reproduce the issue? 
+
+Example:
+
+> Short and descriptive example issue title
+>
+> A summary of the issue with details about the environment it occurs in (Ruby version, Puppet version, Strings version, etc). If
+> suitable, include the steps required to reproduce the bug.
+>
+> 1. This is the first step
+> 2. This is the second step
+> 3. Further steps, etc.
+>
+> Any other information you want to share that is relevant to the issue being
+> reported. This might include the lines of code that you have identified as
+> causing the bug, and potential solutions (and your opinions on their
+> merits).
+
 ## Making Changes
 
 * Create a topic branch from where you want to base your work.
@@ -98,7 +129,6 @@ To cut a new release, from a current `master` checkout:
 # Additional Resources
 
 * [More information on contributing](http://links.puppet.com/contribute-to-puppet)
-* [Bug tracker (Jira)](http://tickets.puppet.com)
 * [Contributor License Agreement](http://links.puppet.com/cla)
 * [General GitHub documentation](http://help.github.com/)
 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)

data/Gemfile

@@ -24,7 +24,13 @@ end
 
 group :acceptance do
   # Litmus has dependencies which require Ruby 2.5 (Puppet 6) or above.
-  gem 'puppet_litmus' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.5.0')
+  if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.5.0')
+    # Until https://github.com/puppetlabs/puppet_litmus/pull/248 is merged we need to use the source of the
+    # of the PR.  Not the greatest and prone to error, but without it, all litmus based testing is broken.
+    # This can be reverted once this PR is merged and Litmus is released with this fix.
+    gem 'puppet_litmus', git: 'https://github.com/michaeltlombardi/puppet_litmus', ref: 'maint/master/fix-upload-file'
+    gem 'net-ssh', '~> 5.2'
+  end
 end
 
 group :development do

data/README.md

@@ -8,18 +8,11 @@ Puppet Strings generates documentation for Puppet code and extensions written in
 |                |                                                                 |
 | -------------- |---------------------------------------------------------------- |
 | *Code*         | [GitHub][repo]                                                  |
-| *Issues*       | [Puppet JIRA Tracker][JIRA]                                     |
+| *Issues*       | [GitHub issues][issues]                                         |
 | *License*      | [Apache 2.0][LICENSE]                                           |
 | *Change log*   | [CHANGELOG.md][changelog]                                       |
 | *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
 
-[repo]: https://github.com/puppetlabs/puppet-strings
-[JIRA]: https://tickets.puppetlabs.com/browse/PDOC
-[LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
-[changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
-[contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
-[committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
-
 ## Installing Puppet Strings
 
 ### Requirements
@@ -135,10 +128,22 @@ An example of run the acceptance tests follow the instructions [here].
 
 ## Support
 
-Please log tickets and issues in our [JIRA tracker][JIRA]. A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others.
+Please log issues in [GitHub issues][issues]. Check out [CONTRIBUTING.md][contributing] for tips on writing _the best_ issues.
 
-There is also an active #puppet channel on the Freenode IRC network.
+A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others.
+
+There is also an active community on the [Puppet community Slack][] in the #forge-modules channel.
 
 We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available.
 
 Bug fixes and ongoing development will occur in minor releases for the current major version. Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.
+
+
+[repo]: https://github.com/puppetlabs/puppet-strings
+[issues]: https://github.com/puppetlabs/puppet-strings/issues
+[LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
+[changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
+[contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
+[committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
+[Puppet community Slack]: https://slack.puppet.com
+

data/Rakefile

@@ -1,4 +1,39 @@
-require 'puppet_litmus/rake_tasks' if Bundler.rubygems.find_name('puppet_litmus').any?
+if Bundler.rubygems.find_name('puppet_litmus').any?
+  require 'puppet_litmus/rake_tasks'
+
+  # This is a _really_ horrible monkey-patch to fix up https://github.com/puppetlabs/bolt/issues/1614
+  # Based on resolution https://github.com/puppetlabs/bolt/pull/1620
+  # This can be removed once this is fixed, released into Bolt and into Litmus
+  require 'bolt_spec/run'
+  module BoltSpec
+    module Run
+      class BoltRunner
+        class << self
+          alias_method :original_with_runner, :with_runner
+        end
+
+        def self.with_runner(config_data, inventory_data)
+          original_with_runner(deep_duplicate_object(config_data), deep_duplicate_object(inventory_data)) { |runner| yield runner }
+        end
+
+        # From https://github.com/puppetlabs/pdk/blob/master/lib/pdk/util.rb
+        # Workaround for https://github.com/puppetlabs/bolt/issues/1614
+        def self.deep_duplicate_object(object)
+          if object.is_a?(Array)
+            object.map { |item| deep_duplicate_object(item) }
+          elsif object.is_a?(Hash)
+            hash = object.dup
+            hash.each_pair { |key, value| hash[key] = deep_duplicate_object(value) }
+            hash
+          else
+            object
+          end
+        end
+      end
+    end
+  end
+end
+
 require 'puppetlabs_spec_helper/tasks/fixtures'
 require 'bundler/gem_tasks'
 require 'puppet-lint/tasks/puppet-lint'
@@ -25,53 +60,6 @@ task :validate do
 end
 
 namespace :litmus do
-  # Install the puppet module fixture on a collection of nodes
-  #
-  # @param :target_node_name [Array] nodes on which to install a puppet module for testing.
-  desc 'install_module_fixtures - build and install module fixtures'
-  task :install_module_fixtures, [:target_node_name] do |_task, args|
-    inventory_hash = inventory_hash_from_inventory_file
-    target_nodes = find_targets(inventory_hash, args[:target_node_name])
-    if target_nodes.empty?
-      puts 'No targets found'
-      exit 0
-    end
-    include BoltSpec::Run
-    require 'pdk/module/build'
-
-    module_fixture_dir = File.expand_path(File.join(File.dirname(__FILE__), 'spec', 'fixtures', 'acceptance', 'modules', 'test'))
-    module_tar = nil
-    Dir.chdir(module_fixture_dir) do
-      opts = {}
-      opts[:force] = true
-      builder = PDK::Module::Build.new(opts)
-      module_tar = builder.build
-      puts 'Built'
-      module_tar = Dir.glob('pkg/*.tar.gz').max_by { |f| File.mtime(f) }
-      raise "Unable to find package in 'pkg/*.tar.gz'" if module_tar.nil?
-      module_tar = File.expand_path(module_tar)
-    end
-
-    target_string = if args[:target_node_name].nil?
-                      'all'
-                    else
-                      args[:target_node_name]
-                    end
-    # TODO: Currently this is Linux only
-    tmp_path = '/tmp/'
-    run_local_command("bundle exec bolt file upload #{module_tar} #{tmp_path}#{File.basename(module_tar)} --nodes #{target_string} --inventoryfile inventory.yaml")
-    install_module_command = "puppet module install #{tmp_path}#{File.basename(module_tar)}"
-    result = run_command(install_module_command, target_nodes, config: nil, inventory: inventory_hash)
-    if result.is_a?(Array)
-      result.each do |node|
-        puts "#{node['node']} failed #{node['result']}" if node['status'] != 'success'
-      end
-    else
-      raise "Failed trying to run '#{install_module_command}' against inventory."
-    end
-    puts 'Installed'
-  end
-
   def install_remote_gem(gem_name, target_nodes, inventory_hash)
     # TODO: Currently this is Linux only
     install_command = "/opt/puppetlabs/puppet/bin/gem install #{gem_name}"
@@ -96,6 +84,7 @@ namespace :litmus do
       puts 'No targets found'
       exit 0
     end
+    require 'bolt_spec/run'
     include BoltSpec::Run
 
     # Build the gem
@@ -113,15 +102,18 @@ namespace :litmus do
                     else
                       args[:target_node_name]
                     end
-    # TODO: Currently this is Linux only
+    # TODO: Currently this is Linux targets only. no windows localhost
     tmp_path = '/tmp/'
-    run_local_command("bundle exec bolt file upload #{gem_tar} #{tmp_path}#{File.basename(gem_tar)} --nodes #{target_string} --inventoryfile inventory.yaml")
-
+    puts 'Copying gem to targets...'
+    run_local_command("bolt file upload #{gem_tar} #{tmp_path}#{File.basename(gem_tar)} --targets #{target_string} --inventoryfile inventory.yaml")
 
     # Install dependent gems
+    puts 'Installing yard gem...'
     install_remote_gem('yard', target_nodes, inventory_hash)
+    puts 'Installing rgen gem...'
     install_remote_gem('rgen', target_nodes, inventory_hash)
     # Install puppet-strings
+    puts 'Installing puppet-strings gem...'
     install_remote_gem(tmp_path + File.basename(gem_tar), target_nodes, inventory_hash)
     puts 'Installed'
   end
@@ -156,7 +148,7 @@ begin
             labels: ["backwards-incompatible"]
           }
         }
-    config.exclude_labels = ['maintenance']
+    config.exclude_labels = ['maintenance','incomplete']
     config.user = 'puppetlabs'
     config.project = 'puppet-strings'
   end

data/lib/puppet-strings.rb

@@ -7,7 +7,7 @@ module PuppetStrings
     types/**/*.pp
     lib/**/*.rb
     tasks/*.json
-    plans/*.pp
+    plans/**/*.pp
   ).freeze
 
   # Generates documentation.

data/lib/puppet-strings/markdown/base.rb

@@ -111,6 +111,11 @@ module PuppetStrings::Markdown
       select_tags('option')
     end
 
+    # @return [Array] enum tag hashes
+    def enums
+      select_tags('enum')
+    end
+
     # @param parameter_name
     #   parameter name to match to option tags
     # @return [Array] option tag hashes that have a parent parameter_name
@@ -119,6 +124,14 @@ module PuppetStrings::Markdown
       opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
     end
 
+    # @param parameter_name
+    #   parameter name to match to enum tags
+    # @return [Array] enum tag hashes that have a parent parameter_name
+    def enums_for_param(parameter_name)
+      enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
+      enums_for_p unless enums_for_p.nil? || enums_for_p.length.zero?
+    end
+
     # @return [Hash] any defaults found for the component
     def defaults
       @registry[:defaults] unless @registry[:defaults].nil?

data/lib/puppet-strings/markdown/templates/classes_and_defines.erb

@@ -65,6 +65,14 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
 Default value: <%= value_string(defaults[param[:name]]) %>

data/lib/puppet-strings/markdown/templates/data_type.erb

@@ -69,6 +69,14 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if defaults && defaults[param[:name]] -%>
 Default value: <%= value_string(defaults[param[:name]]) %>

data/lib/puppet-strings/markdown/templates/function.erb

@@ -87,6 +87,14 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if sig.enums_for_param(param[:name]) -%>
+Options:
+
+<% sig.enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% end -%>
 <% end -%>

data/lib/puppet-strings/markdown/templates/resource_type.erb

@@ -77,6 +77,14 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(prop[:name]) -%>
+Options:
+
+<% enums_for_param(prop[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if prop[:default] -%>
 Default value: <%= prop[:default] %>
@@ -117,6 +125,14 @@ Options:
 * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
 <% end -%>
 
+<% end -%>
+<% if enums_for_param(param[:name]) -%>
+Options:
+
+<% enums_for_param(param[:name]).each do |e| -%>
+* **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
+<% end -%>
+
 <% end -%>
 <% if param[:default] -%>
 Default value: <%= value_string(param[:default]) %>

data/lib/puppet-strings/version.rb

@@ -1,3 +1,3 @@
 module PuppetStrings
-  VERSION = '2.3.1'.freeze
+  VERSION = '2.4.0'.freeze
 end

data/lib/puppet-strings/yard.rb

@@ -11,6 +11,9 @@ module PuppetStrings::Yard
   # Sets up YARD for use with puppet-strings.
   # @return [void]
   def self.setup!
+    # Register our factory
+    YARD::Tags::Library.default_factory = PuppetStrings::Yard::Tags::Factory
+
     # Register the template path
     YARD::Templates::Engine.register_template_path(File.join(File.dirname(__FILE__), 'yard', 'templates'))
 
@@ -30,6 +33,9 @@ module PuppetStrings::Yard
     # Register the summary tag
     PuppetStrings::Yard::Tags::SummaryTag.register!
 
+    # Register the enum tag
+    PuppetStrings::Yard::Tags::EnumTag.register!
+
     # Ignore documentation on Puppet DSL calls
     # This prevents the YARD DSL parser from emitting warnings for Puppet's Ruby DSL
     YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['create_function'] = true

data/lib/puppet-strings/yard/code_objects/function.rb

@@ -88,10 +88,10 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
     if self.has_tag? :overload
       # loop over overloads and append onto the signatures array
       self.tags(:overload).each do |o|
-        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, %i[param option return example]) }
+        hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, %i[param option enum return example]) }
       end
     else
-      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option return example]) }
+      hash[:signatures] << { :signature => self.signature, :docstring =>  PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example]) }
     end
 
     hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)

data/lib/puppet-strings/yard/tags.rb

@@ -1,7 +1,9 @@
 # The module for custom YARD tags.
 module PuppetStrings::Yard::Tags
+  require 'puppet-strings/yard/tags/factory'
   require 'puppet-strings/yard/tags/parameter_directive'
   require 'puppet-strings/yard/tags/property_directive'
   require 'puppet-strings/yard/tags/overload_tag'
   require 'puppet-strings/yard/tags/summary_tag'
+  require 'puppet-strings/yard/tags/enum_tag'
 end

data/lib/puppet-strings/yard/tags/enum_tag.rb

@@ -0,0 +1,12 @@
+require 'yard/tags/option_tag'
+
+# Implements an enum tag for describing enumerated value data types
+
+class PuppetStrings::Yard::Tags::EnumTag < YARD::Tags::OptionTag
+  # Registers the tag with YARD.
+  # @return [void]
+  def self.register!
+    YARD::Tags::Library.define_tag("puppet.enum", :enum, :with_enums)
+    YARD::Tags::Library.visible_tags.place(:enum).after(:option)
+  end
+end

data/lib/puppet-strings/yard/tags/factory.rb

@@ -0,0 +1,16 @@
+require 'yard/tags/default_factory'
+require 'puppet-strings/yard/tags/enum_tag'
+
+class PuppetStrings::Yard::Tags::Factory < YARD::Tags::DefaultFactory
+
+  # Parses tag text and creates a new enum tag type. Modeled after
+  # the parse_tag_with_options method in YARD::Tags::DefaultFactory.
+  #
+  # @param tag_name        the name of the tag to parse
+  # @param [String] text   the raw tag text
+  # @return [Tag]          a tag object with the tag_name, name, and nested Tag as type
+  def parse_tag_with_enums(tag_name, text)
+    name, text = *extract_name_from_text(text)
+    PuppetStrings::Yard::Tags::EnumTag.new(tag_name, name, parse_tag_with_name(tag_name, text))
+  end
+end

data/lib/puppet-strings/yard/templates/default/tags/html/enum.erb

@@ -0,0 +1,17 @@
+<% if object.has_tag?(:enum) %>
+  <% object.parameters.each do |param, default| %>
+    <% tags = object.tags(:enum).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
+    <% next if tags.empty? %>
+    <p class="tag_title">Enum Options (<tt><%= param %></tt>):</p>
+    <ul class="option">
+      <% for tag in tags %>
+        <li>
+          <span class="name"><%= tag.pair.name %></span>
+          <% if tag.pair.text && tag.pair.text =~ /\S/ %>
+            &mdash; <%= htmlify_line(tag.pair.text) %>
+          <% end %>
+        </li>
+      <% end %>
+    </ul>
+  <% end %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/tags/setup.rb

@@ -16,3 +16,9 @@ end
 def overload
   erb(if object.type == :puppet_function then :puppet_overload else :overload end)
 end
+
+# Renders the enum section.
+# @return [String] Returns the rendered section.
+def enum
+  erb(:enum)
+end

data/lib/puppet-strings/yard/util.rb

@@ -38,11 +38,11 @@ module PuppetStrings::Yard::Util
       next t.to_hash if t.respond_to?(:to_hash)
 
       tag = { tag_name: t.tag_name }
-      # grab nested information for @option tags
-      if tag[:tag_name] == 'option'
+      # grab nested information for @option and @enum tags
+      if tag[:tag_name] == 'option' || tag[:tag_name] == 'enum'
         tag[:opt_name] = t.pair.name
         tag[:opt_text] = t.pair.text
-        tag[:opt_types] = t.pair.types
+        tag[:opt_types] = t.pair.types if t.pair.types
         tag[:parent] = t.name
       end
       tag[:text] = t.text if t.text

data/spec/acceptance/emit_json_options_spec.rb

@@ -49,7 +49,7 @@ describe 'Emitting JSON' do
     { :title => '--emit-json-stdout', :cmd_line => '--emit-json-stdout' }
   ].each do |testcase|
     it "should emit JSON to stdout when using #{testcase[:title]}" do
-      output = PuppetLitmus::Serverspec.run_shell("puppet strings generate #{testcase[:cmd_line]} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\"").stdout.chomp
+      output = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate #{testcase[:cmd_line]} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\"").stdout.chomp
       expect(JSON.parse(output)).to eq(expected)
     end
   end
@@ -61,7 +61,7 @@ describe 'Emitting JSON' do
     it "should write JSON to a file when using #{testcase[:title]}" do
       tmpfile = File.join(@remote_tmp_path, 'json_output.json')
       cmd = "puppet strings generate #{testcase[:cmd_line].gsub('TMPFILE', tmpfile)} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\""
-      PuppetLitmus::Serverspec.run_shell(cmd)
+      PuppetLitmus::PuppetHelpers.run_shell(cmd)
       output = JSON.parse(file(tmpfile).content)
       expect(output).to eq(expected)
     end

data/spec/acceptance/generate_markdown_spec.rb

@@ -35,13 +35,13 @@ The name of the service
 
   it 'should render Markdown to stdout when using --format markdown' do
     skip('This test is broken. Does not output to STDOUT by default.')
-    output = PuppetLitmus::Serverspec.run_shell("puppet strings generate --format markdown \"#{@test_module_path}/manifests/init.pp\"").stdout.chomp
+    output = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate --format markdown \"#{@test_module_path}/manifests/init.pp\"").stdout.chomp
     expect(output).to eq(expected)
   end
 
   it 'should write Markdown to a file when using --format markdown and --out' do
     tmpfile = File.join(@remote_tmp_path, 'md_output.md')
-    remote = PuppetLitmus::Serverspec.run_shell("puppet strings generate --format markdown --out \"#{tmpfile}\" \"#{@test_module_path}/manifests/init.pp\"")
+    remote = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate --format markdown --out \"#{tmpfile}\" \"#{@test_module_path}/manifests/init.pp\"")
     expect(file(tmpfile)).to contain expected
   end
 end

data/spec/acceptance/running_strings_generate_spec.rb

@@ -4,10 +4,10 @@ include PuppetLitmus # rubocop:disable Style/MixinUsage This is fine
 describe 'Generating module documentation using generate action' do
   before :all do
     # TODO: Linux only
-    @sut_work_dir = PuppetLitmus::Serverspec.run_shell("pwd").stdout.chomp
+    @sut_work_dir = PuppetLitmus::PuppetHelpers.run_shell("pwd").stdout.chomp
 
     test_module_path = sut_module_path(/Module test/)
-    PuppetLitmus::Serverspec.run_shell("puppet strings generate \"#{test_module_path}/**/*.{rb,pp}\"")
+    PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate \"#{test_module_path}/**/*.{rb,pp}\"")
   end
 
   def expect_file_contain(path, expected_contents)
@@ -75,4 +75,14 @@ describe 'Generating module documentation using generate action' do
       'A simple elephant type.',
     ])
   end
+
+  it 'should generate documentation for enum tag' do
+    expect_file_contain('doc/puppet_classes/test.html', [
+      '<p class="tag_title">Enum Options (<tt>myenum</tt>):</p>',
+      '<span class="name">a</span>',
+      "&mdash; <div class='inline'>\n<p>Option A</p>\n</div>",
+      '<span class="name">b</span>',
+      "&mdash; <div class='inline'>\n<p>Option B</p>\n</div>",
+    ])
+  end
 end

data/spec/fixtures/acceptance/modules/test/manifests/init.pp

@@ -7,9 +7,13 @@
 #
 # @param package_name The name of the package
 # @param service_name The name of the service
+# @param myenum
+# @enum myenum a Option A
+# @enum myenum b Option B
 class test (
   $package_name = $test::params::package_name,
   $service_name = $test::params::service_name,
+  Enum['a', 'b'] $myenum = 'a',
 
 ) inherits test::params {
 

data/spec/fixtures/unit/markdown/output.md

@@ -101,6 +101,19 @@ Third param.
 
 Default value: 'hi'
 
+##### `param4`
+
+Data type: `Enum['one', 'two']`
+
+Fourth param.
+
+Options:
+
+* **:one**: One option
+* **:two**: Second option
+
+Default value: 'two'
+
 ## Defined types
 
 ### klass::dt
@@ -162,6 +175,19 @@ Fourth param.
 
 Default value: `true`
 
+##### `param5`
+
+Data type: `Enum['a', 'b']`
+
+Fifth param.
+
+Options:
+
+* **:a**: Option A
+* **:b**: Option B
+
+Default value: 'a'
+
 ## Resource types
 
 ### apt_key
@@ -238,6 +264,11 @@ Aliases: "up"=>"present", "down"=>"absent"
 
 What state the database should be in.
 
+Options:
+
+* **:up**: Upstate
+* **:down**: Downstate
+
 Default value: up
 
 ##### `file`
@@ -292,7 +323,7 @@ A simple Puppet function.
 $result = func(1, 2)
 ```
 
-#### `func(Integer $param1, Any $param2, String $param3 = hi)`
+#### `func(Integer $param1, Any $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes')`
 
 A simple Puppet function.
 
@@ -331,6 +362,17 @@ Options:
 
 * **:param3opt** `Array`: Something about this option
 
+##### `param4`
+
+Data type: `Enum['yes', 'no']`
+
+Fourth param.
+
+Options:
+
+* **:yes**: Yes option.
+* **:no**: No option.
+
 ### func3x
 
 Type: Ruby 3.x API
@@ -391,7 +433,7 @@ $result = func4x(1, 'foo')
 $result = func4x(1, 'foo', ['bar'])
 ```
 
-#### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
+#### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3, Optional[Enum[one, two]] $param4)`
 
 An overview for the first overload.
 
@@ -428,6 +470,17 @@ Data type: `Optional[Array[String]]`
 
 The third parameter.
 
+##### `param4`
+
+Data type: `Optional[Enum[one, two]]`
+
+The fourth parameter.
+
+Options:
+
+* **:one**: Option one.
+* **:two**: Option two.
+
 #### `func4x(Boolean $param, Callable &$block)`
 
 An overview for the second overload.

data/spec/fixtures/unit/markdown/output_with_data_types.md

@@ -107,6 +107,19 @@ Third param.
 
 Default value: 'hi'
 
+##### `param4`
+
+Data type: `Enum['one', 'two']`
+
+Fourth param.
+
+Options:
+
+* **:one**: One option
+* **:two**: Second option
+
+Default value: 'two'
+
 ## Defined types
 
 ### klass::dt
@@ -168,6 +181,19 @@ Fourth param.
 
 Default value: `true`
 
+##### `param5`
+
+Data type: `Enum['a', 'b']`
+
+Fifth param.
+
+Options:
+
+* **:a**: Option A
+* **:b**: Option B
+
+Default value: 'a'
+
 ## Resource types
 
 ### apt_key
@@ -244,6 +270,11 @@ Aliases: "up"=>"present", "down"=>"absent"
 
 What state the database should be in.
 
+Options:
+
+* **:up**: Upstate
+* **:down**: Downstate
+
 Default value: up
 
 ##### `file`
@@ -298,7 +329,7 @@ A simple Puppet function.
 $result = func(1, 2)
 ```
 
-#### `func(Integer $param1, Any $param2, String $param3 = hi)`
+#### `func(Integer $param1, Any $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes')`
 
 A simple Puppet function.
 
@@ -337,6 +368,17 @@ Options:
 
 * **:param3opt** `Array`: Something about this option
 
+##### `param4`
+
+Data type: `Enum['yes', 'no']`
+
+Fourth param.
+
+Options:
+
+* **:yes**: Yes option.
+* **:no**: No option.
+
 ### func3x
 
 Type: Ruby 3.x API
@@ -397,7 +439,7 @@ $result = func4x(1, 'foo')
 $result = func4x(1, 'foo', ['bar'])
 ```
 
-#### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
+#### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3, Optional[Enum[one, two]] $param4)`
 
 An overview for the first overload.
 
@@ -434,6 +476,17 @@ Data type: `Optional[Array[String]]`
 
 The third parameter.
 
+##### `param4`
+
+Data type: `Optional[Enum[one, two]]`
+
+The fourth parameter.
+
+Options:
+
+* **:one**: Option one.
+* **:two**: Option two.
+
 #### `func4x(Boolean $param, Callable &$block)`
 
 An overview for the second overload.

data/spec/fixtures/unit/markdown/output_with_plan.md

@@ -105,6 +105,19 @@ Third param.
 
 Default value: 'hi'
 
+##### `param4`
+
+Data type: `Enum['one', 'two']`
+
+Fourth param.
+
+Options:
+
+* **:one**: One option
+* **:two**: Second option
+
+Default value: 'two'
+
 ## Defined types
 
 ### klass::dt
@@ -166,6 +179,19 @@ Fourth param.
 
 Default value: `true`
 
+##### `param5`
+
+Data type: `Enum['a', 'b']`
+
+Fifth param.
+
+Options:
+
+* **:a**: Option A
+* **:b**: Option B
+
+Default value: 'a'
+
 ## Resource types
 
 ### apt_key
@@ -242,6 +268,11 @@ Aliases: "up"=>"present", "down"=>"absent"
 
 What state the database should be in.
 
+Options:
+
+* **:up**: Upstate
+* **:down**: Downstate
+
 Default value: up
 
 ##### `file`
@@ -296,7 +327,7 @@ A simple Puppet function.
 $result = func(1, 2)
 ```
 
-#### `func(Integer $param1, Any $param2, String $param3 = hi)`
+#### `func(Integer $param1, Any $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes')`
 
 A simple Puppet function.
 
@@ -335,6 +366,17 @@ Options:
 
 * **:param3opt** `Array`: Something about this option
 
+##### `param4`
+
+Data type: `Enum['yes', 'no']`
+
+Fourth param.
+
+Options:
+
+* **:yes**: Yes option.
+* **:no**: No option.
+
 ### func3x
 
 Type: Ruby 3.x API
@@ -395,7 +437,7 @@ $result = func4x(1, 'foo')
 $result = func4x(1, 'foo', ['bar'])
 ```
 
-#### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
+#### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3, Optional[Enum[one, two]] $param4)`
 
 An overview for the first overload.
 
@@ -432,6 +474,17 @@ Data type: `Optional[Array[String]]`
 
 The third parameter.
 
+##### `param4`
+
+Data type: `Optional[Enum[one, two]]`
+
+The fourth parameter.
+
+Options:
+
+* **:one**: Option one.
+* **:two**: Option two.
+
 #### `func4x(Boolean $param, Callable &$block)`
 
 An overview for the second overload.

data/spec/spec_helper_acceptance_local.rb

@@ -1,5 +1,5 @@
 def sut_module_path(module_regex)
-  modules = JSON.parse(PuppetLitmus::Serverspec.run_shell('puppet module list --render-as json').stdout)
+  modules = JSON.parse(PuppetLitmus::PuppetHelpers.run_shell('puppet module list --render-as json').stdout)
   test_module_info = modules['modules_by_path'].values.flatten.find { |mod_info| mod_info =~ module_regex }
   test_module_info.match(/\(([^)]*)\)/)[1]
 end

data/spec/unit/puppet-strings/markdown_spec.rb

@@ -29,11 +29,15 @@ describe PuppetStrings::Markdown do
 # @option param2 [String] :opt1 something about opt1
 # @option param2 [Hash] :opt2 a hash of stuff
 # @param param3 Third param.
+# @param param4 Fourth param.
+# @enum param4 :one One option
+# @enum param4 :two Second option
 #
 class klass (
   Integer $param1 = 1,
   $param2 = undef,
-  String $param3 = 'hi'
+  String $param3 = 'hi',
+  Enum['one', 'two'] $param4 = 'two',
 ) inherits foo::bar {
 }
 
@@ -58,11 +62,15 @@ class noparams () {}
 # @option param2 [Hash] :opt2 a hash of stuff
 # @param param3 Third param.
 # @param param4 Fourth param.
+# @param param5 Fifth param.
+# @enum param5 :a Option A
+# @enum param5 :b Option B
 define klass::dt (
   Integer $param1 = 44,
   $param2,
   String $param3 = 'hi',
-  Boolean $param4 = true
+  Boolean $param4 = true,
+  Enum['a', 'b'] $param5 = 'a'
 ) {
 }
     SOURCE
@@ -98,11 +106,14 @@ define klass::dt (
 # @param param2 Second param.
 # @param param3 Third param.
 # @option param3 [Array] :param3opt Something about this option
+# @param param4 Fourth param.
+# @enum param4 :yes Yes option.
+# @enum param4 :no No option.
 # @raise SomeError this is some error
 # @return [Undef] Returns nothing.
 # @example Test
 #   $result = func(1, 2)
-function func(Integer $param1, $param2, String $param3 = hi) {
+function func(Integer $param1, $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes') {
 }
     SOURCE
 
@@ -122,6 +133,9 @@ Puppet::Functions.create_function(:func4x) do
   # @option param2 [String] :option an option
   # @option param2 [String] :option2 another option
   # @param param3 The third parameter.
+  # @param param4 The fourth parameter.
+  # @enum param4 :one Option one.
+  # @enum param4 :two Option two.
   # @return Returns nothing.
   # @example Calling the function foo
   #   $result = func4x(1, 'foooo')
@@ -130,6 +144,7 @@ Puppet::Functions.create_function(:func4x) do
     param          'Integer',       :param1
     param          'Any',           :param2
     optional_param 'Array[String]', :param3
+    optional_param 'Enum[one, two]', :param4
     return_type 'Undef'
   end
 
@@ -183,6 +198,8 @@ Puppet::Type.newtype(:database) do
   desc <<-DESC
 An example database server type.
 @option opts :foo bar
+@enum ensure :up Upstate
+@enum ensure :down Downstate
 @raise SomeError
 @example here's an example
  database { 'foo':

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: puppet-strings
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - Puppet Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-09-23 00:00:00.000000000 Z
+date: 2020-02-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: yard
@@ -128,6 +128,8 @@ files:
 - lib/puppet-strings/yard/parsers/puppet/parser.rb
 - lib/puppet-strings/yard/parsers/puppet/statement.rb
 - lib/puppet-strings/yard/tags.rb
+- lib/puppet-strings/yard/tags/enum_tag.rb
+- lib/puppet-strings/yard/tags/factory.rb
 - lib/puppet-strings/yard/tags/overload_tag.rb
 - lib/puppet-strings/yard/tags/parameter_directive.rb
 - lib/puppet-strings/yard/tags/property_directive.rb
@@ -217,6 +219,7 @@ files:
 - lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb
 - lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb
 - lib/puppet-strings/yard/templates/default/puppet_type/html/todo.erb
+- lib/puppet-strings/yard/templates/default/tags/html/enum.erb
 - lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb
 - lib/puppet-strings/yard/templates/default/tags/setup.rb
 - lib/puppet-strings/yard/util.rb
@@ -282,7 +285,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - puppet, >= 4.0.0
-rubygems_version: 3.0.3
+rubygems_version: 3.0.4
 signing_key: 
 specification_version: 4
 summary: Puppet documentation via YARD