Extend doc generation to defined types

Puppet Yardoc now generates documentation for defined types in addition to host
classes. The actual change was fairly small, however this patch is quite large
as most of the host class bits were re-architected to inherit from defined
types. Host classes are basically the same as defined types with the addition
of inheritance. Pops also models Host Class using a similar inheritance
relationship.

lib/puppetx/yardoc/yard/code_objects.rb

@@ -1 +1,2 @@
+require_relative 'code_objects/defined_type_object'
 require_relative 'code_objects/host_class_object'

lib/puppetx/yardoc/yard/code_objects/defined_type_object.rb

@@ -0,0 +1,37 @@
+require 'yard'
+require 'puppet/pops'
+
+require_relative '../../../yardoc'
+
+module Puppetx::Yardoc::YARD::CodeObjects
+  class DefinedTypeObject < YARD::CodeObjects::NamespaceObject
+    # A list of parameters attached to this class.
+    # @return [Array<Array(String, String)>]
+    attr_accessor :parameters
+
+    # The `YARD::Codeobjects::Base` class pulls a bunch of shenanigans to
+    # insert proxy namespaces. Unfortunately, said shenanigans pick up on the
+    # `::` in Puppet names and start to mangle things based on rules for the
+    # Ruby language.
+    #
+    # Therefore, we must override `new` for great justice.
+    #
+    # TODO: Ask around on the YARD mailing list to see if there is a way around
+    # this ugliness.
+    #
+    # Alternately, consider ensuring all `proxy` objects resolve to a
+    # placeholder `NamespaceObject` as the name mangling behavior of these is
+    # easier to control.
+    def self.new(namespace, name, *args, &block)
+      # Standard Ruby boilerplate for `new`
+      obj = self.allocate
+      obj.send :initialize, namespace, name, *args
+
+      # The last bit of `YARD::CodeObjects::Base.new`.
+      existing_obj = YARD::Registry.at(obj.path)
+      obj = existing_obj if existing_obj && existing_obj.class == self
+      yield(obj) if block_given?
+      obj
+    end
+  end
+end

lib/puppetx/yardoc/yard/code_objects/host_class_object.rb

@@ -1,43 +1,11 @@
-require 'yard'
-require 'puppet/pops'
-
-require_relative '../../../yardoc'
+require_relative 'defined_type_object'
 
 module Puppetx::Yardoc::YARD::CodeObjects
-  class HostClassObject < YARD::CodeObjects::NamespaceObject
+  class HostClassObject < DefinedTypeObject
     # The {HostClassObject} that this class inherits from, if any.
     # @return [HostClassObject, Proxy, nil]
     attr_accessor :parent_class
 
-    # A list of parameters attached to this class.
-    # @return [Array<Array(String, String)>]
-    attr_accessor :parameters
-
-    # The `YARD::Codeobjects::Base` class pulls a bunch of shenanigans to
-    # insert proxy namespaces. Unfortunately, said shenanigans pick up on the
-    # `::` in Puppet names and start to mangle things based on rules for the
-    # Ruby language.
-    #
-    # Therefore, we must override `new` for great justice.
-    #
-    # TODO: Ask around on the YARD mailing list to see if there is a way around
-    # this ugliness.
-    #
-    # Alternately, consider ensuring all `proxy` objects resolve to a
-    # placeholder `NamespaceObject` as the name mangling behavior of these is
-    # easier to control.
-    def self.new(namespace, name, *args, &block)
-      # Standard Ruby boilerplate for `new`
-      obj = self.allocate
-      obj.send :initialize, namespace, name, *args
-
-      # The last bit of `YARD::CodeObjects::Base.new`.
-      existing_obj = YARD::Registry.at(obj.path)
-      obj = existing_obj if existing_obj && existing_obj.class == self
-      yield(obj) if block_given?
-      obj
-    end
-
     # NOTE: `include_mods` is never used as it makes no sense for Puppet, but
     # this is called by `YARD::Registry` and it will pass a parameter.
     def inheritance_tree(include_mods = false)

lib/puppetx/yardoc/yard/handlers.rb

@@ -1,2 +1,3 @@
 require_relative 'handlers/base'
+require_relative 'handlers/defined_type_handler'
 require_relative 'handlers/host_class_handler'

lib/puppetx/yardoc/yard/handlers/defined_type_handler.rb

@@ -0,0 +1,18 @@
+require_relative 'base'
+
+module Puppetx::Yardoc::YARD::Handlers
+  class DefinedTypeHandler < Base
+    handles ResourceTypeDefinition
+
+    process do
+      obj = DefinedTypeObject.new(:root, statement.pops_obj.name) do |o|
+        o.parameters = statement.parameters.map do |a|
+          param_tuple = [a[0].pops_obj.name]
+          param_tuple << ( a[1].nil? ? nil : a[1].source )
+        end
+      end
+
+      register obj
+    end
+  end
+end

lib/puppetx/yardoc/yard/monkey_patches.rb

@@ -6,7 +6,7 @@ require 'yard'
 
 class YARD::CLI::Yardoc
   def all_objects
-    YARD::Registry.all(:root, :module, :class, :hostclass)
+    YARD::Registry.all(:root, :module, :class, :hostclass, :definedtype)
   end
 end
 
@@ -14,4 +14,8 @@ class YARD::CLI::Stats
   def stats_for_hostclasses
     output 'Puppet Classes', *type_statistics(:hostclass)
   end
+
+  def stats_for_definedtypes
+    output 'Puppet Types', *type_statistics(:definedtype)
+  end
 end

lib/puppetx/yardoc/yard/templates/default/definedtype/html/setup.rb

@@ -0,0 +1 @@
+include T('default/module/html')

lib/puppetx/yardoc/yard/templates/default/definedtype/setup.rb

@@ -0,0 +1,10 @@
+include T('default/module')
+
+def init
+  sections :header, :box_info, :pre_docstring, T('docstring'), :parameter_details
+end
+
+def parameter_details
+  return if object.parameters.empty?
+  erb(:parameter_details)
+end

lib/puppetx/yardoc/yard/templates/default/hostclass/html/setup.rb

@@ -1 +1 @@
-include T('default/module/html')
+include T('default/definedtype/html')

lib/puppetx/yardoc/yard/templates/default/hostclass/setup.rb

@@ -1,12 +1,8 @@
-include T('default/module')
+include T('default/definedtype')
 
 def init
-  sections :header, :box_info, :pre_docstring, T('docstring'), :parameter_details, :subclasses
-end
-
-def parameter_details
-  return if object.parameters.empty?
-  erb(:parameter_details)
+  super
+  sections.push :subclasses
 end
 
 def subclasses

lib/puppetx/yardoc/yard/templates/default/layout/html/setup.rb

@@ -2,7 +2,7 @@
 # @objects_by_letter prevents that. Submit a pull request.
 def index
   @objects_by_letter = {}
-  objects = Registry.all(:class, :module, :hostclass).sort_by {|o| o.name.to_s }
+  objects = Registry.all(:class, :module, :hostclass, :definedtype).sort_by {|o| o.name.to_s }
   objects = run_verifier(objects)
   objects.each {|o| (@objects_by_letter[o.name.to_s[0,1].upcase] ||= []) << o }
   erb(:index)