(PDOC-295) Add 'enum' tag support for Enum data types

Enum data types would benefit from the ability to add extended
documentation on each option similarly to the '@option' tag
for hashes. The option type is not a good fit for Enum data
type parameters as it requires data types to be specified,
which doesn't make sense in the context of a Enum type.

Author: seanmil

lib/puppet-strings/markdown/base.rb

@@ -111,6 +111,11 @@ def options
       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 @@ def options_for_param(parameter_name)
       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?

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]]) %>

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]]) %>

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 -%>

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]) %>

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 @@ def self.setup!
     # 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

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

@@ -88,10 +88,10 @@ def to_hash
     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)

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

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

@@ -0,0 +1,11 @@
+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)
+  end
+end

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