Merge pull request #215 from seanmil/add_enum_tag

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

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

lib/puppet-strings/yard/util.rb

@@ -38,11 +38,11 @@ def self.tags_to_hashes(tags)
       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

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.