(puppetlabsGH-225) Document functions in Puppet Datatypes

Previously the puppet datatype handler only documented attributes, not functions
for example [1].  This commit updates the data type handler to read in the
function information and then allow that to be used by puppet-strings in its
JSON, Markdown and HTML renderers.  This commit also adds tests for many
different scenarios and all three rendering types.

[1] https://github.com/puppetlabs/puppet/blob/3e03e734dda415272ec156b03ed9f021ba243228/lib/puppet/datatypes/error.rb#L13-L15

lib/puppet-strings/markdown/data_type.rb

@@ -4,15 +4,31 @@ module PuppetStrings::Markdown
   # This class encapsualtes ruby data types and puppet type aliases
   class DataType < Base
     attr_reader :alias_of
+    attr_reader :functions
 
     def initialize(registry)
       @template = 'data_type.erb'
       super(registry, 'data type')
       @alias_of = registry[:alias_of] unless registry[:alias_of].nil?
+      @functions = @registry[:functions].nil? ? nil : @registry[:functions].map { |func| DataType::Function.new(func) }
     end
 
     def render
       super(@template)
     end
   end
+
+  class DataType::Function < Base
+    def initialize(registry)
+      super(registry, 'data_type_function')
+    end
+
+    def render
+      super('data_type_function.erb')
+    end
+
+    def signature
+      @registry[:signature]
+    end
+  end
 end

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

@@ -84,3 +84,10 @@ Default value: <%= value_string(defaults[param[:name]]) %>
 <% end -%>
 <% end -%>
 <% end -%>
+<% if functions -%>
+#### Functions
+
+The following functions are available in the `<%= name %>` <%= @type %>.
+
+<% functions.each do |func| -%><%= func.render -%><% end -%>
+<% end -%>

lib/puppet-strings/markdown/templates/data_type_function.erb

@@ -0,0 +1,67 @@
+### <%= name %>
+
+#### `<%= signature %>`
+
+<% if text -%>
+<%= text %>
+
+<% elsif summary -%>
+<%= summary %>
+
+<% else -%>
+<%= "The #{name} function." %>
+
+<% end -%>
+<% if note -%>
+* **Note** <%= note %>
+
+<% end -%>
+<% if return_type -%>
+Returns: `<%= return_type %>`<% if return_val %> <%= return_val %><% end %>
+
+<% end -%>
+<% if raises -%>
+Raises:
+<% raises.each do |r| -%>
+* <%= error_type(r[:text]) %> <%= error_text(r[:text]) %>
+<% end -%>
+
+<% end -%>
+<% if examples -%>
+##### Examples
+
+<% examples.each do |eg| -%>
+###### <%= eg[:name] %>
+
+```puppet
+<%= eg[:text] %>
+```
+
+<% end -%>
+<% end -%>
+<% if params -%>
+<% params.each do |param| -%>
+##### `<%= param[:name]  %>`
+
+Data type: `<%= param[:types][0] %>`
+
+<%= param[:text] %>
+
+<% if options_for_param(param[:name]) -%>
+Options:
+
+<% options_for_param(param[:name]).each do |o| -%>
+* **<%= 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 -%>
+<% end -%>
+<% end -%>

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

@@ -24,7 +24,6 @@ class PuppetStrings::Yard::CodeObjects::DataType < PuppetStrings::Yard::CodeObje
   # @return [void]
   def initialize(name)
     super(PuppetStrings::Yard::CodeObjects::DataTypes.instance, name)
-    @parameters = []
     @defaults = {}
   end
 
@@ -41,10 +40,6 @@ def source
     nil
   end
 
-  def parameter_exist?(name)
-    !docstring.tags(:param).find { |item| item.name == name }.nil?
-  end
-
   def add_parameter(name, type, default)
     tag = docstring.tags(:param).find { |item| item.name == name }
     if tag.nil?
@@ -65,16 +60,41 @@ def parameters
     docstring.tags(:param).map { |tag| [tag.name, defaults[tag.name]] }
   end
 
+  def add_function(name, return_type, parameter_types)
+    meth_obj = YARD::CodeObjects::MethodObject.new(self, name, :class)
+
+    # Add return tag
+    meth_obj.add_tag(YARD::Tags::Tag.new(:return, '', return_type))
+
+    # Add parameters
+    parameter_types.each_with_index do |param_type, index|
+      meth_obj.add_tag(YARD::Tags::Tag.new(:param, '', [param_type], "param#{index + 1}"))
+    end
+
+    self.meths << meth_obj
+  end
+
+  def functions
+    meths
+  end
+
   # Converts the code object to a hash representation.
   # @return [Hash] Returns a hash representation of the code object.
   def to_hash
     hash = {}
     hash[:name] = name
     hash[:file] = file
     hash[:line] = line
-    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
+    hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example])
     hash[:defaults] = defaults unless defaults.empty?
     hash[:source] = source unless source && source.empty?
+    hash[:functions] = functions.map do |func|
+      {
+        name: func.name,
+        signature: func.signature,
+        docstring: PuppetStrings::Yard::Util.docstring_to_hash(func.docstring, %i[param option enum return example])
+      }
+    end
     hash
   end
 end