(#18023) Document user facing classes using yardoc and show api.

This adds yardoc to user facing classes Type, Parameter, Property,
Provider, Report, as well as classes used by these via inclusion or
delegation and where documetation was most relevant to add at the source.

This also includes puppet specific tags (@comment, and @dsl), puppet
specific templates (shows DSL for elements marked with @dsl), as well
as some general improvements to the default yard templates.

As this is the first stab at providing more comprehensive code
documentation, there are many unanswered questions in the documentation
that are marked with @todo, or ??? to indicate uncertainty.
More investigation is required to update these.

Many methods are marked as being non api. As this documentation is not final,
and only covers a portion of the puppet code base, the lack of a "private"
tag being displayed should not yet be taken as authoritiative indication
that it is api.

.yardopts

@@ -7,5 +7,7 @@
 --transitive-tag status
 --tag comment
 --hide-tag comment
+--tag dsl:"DSL"
 --no-transitive-tag api
+--template-path yardoc/templates
 lib/**/*.rb

lib/puppet/metatype/manager.rb

@@ -2,20 +2,29 @@
 require 'puppet/util/classgen'
 require 'puppet/node/environment'
 
-# Methods dealing with Type management.  This module gets included into the
-# Puppet::Type class, it's just split out here for clarity.
+# This module defines methods dealing with Type management.
+# This module gets included into the Puppet::Type class, it's just split out here for clarity.
+# @api public
+#
 module Puppet::MetaType
 module Manager
   include Puppet::Util::ClassGen
 
-  # remove all type instances; this is mostly only useful for testing
+  # An implementation specific method that removes all type instances during testing.
+  # @note Only use this method for testing purposes.
+  # @api private
+  #
   def allclear
     @types.each { |name, type|
       type.clear
     }
   end
 
-  # iterate across all of the subclasses of Type
+  # Iterates over all already loaded Type subclasses.
+  # @yield [t] a block receiving each type
+  # @yieldparam t [Puppet::Type] each defined type
+  # @yieldreturn [Object] the last returned object is also returned from this method
+  # @return [Object] the last returned value from the block.
   def eachtype
     @types.each do |name, type|
       # Only consider types that have names
@@ -25,12 +34,31 @@ def eachtype
     end
   end
 
-  # Load all types.  Only currently used for documentation.
+  # Loads all types.  
+  # @note Should only be used for purposes such as generating documentation as this is potentially a very
+  #  expensive operation.
+  # @return [void]
+  #
   def loadall
     typeloader.loadall
   end
 
-  # Define a new type.
+  # Defines a new type or redefines an existing type with the given name.
+  # A convenience method on the form `new<name>` where name is the name of the type is also created.
+  # (If this generated method happens to clash with an existing method, a warning is issued and the original
+  # method is kept).
+  #
+  # @param name [String] the name of the type to create or redefine.
+  # @param options [Hash] options passed on to {Puppet::Util::ClassGen#genclass} as the option `:attributes` after
+  #   first having removed any present `:parent` option.
+  # @option options [Puppet::Type] :parent the parent (super type) of this type. If nil, the default is
+  #   Puppet::Type. This option is not passed on as an attribute to genclass.
+  # @yield [ ] a block evaluated in the context of the created class, thus allowing further detailing of
+  #   that class.
+  # @return [Class<inherits Puppet::Type>] the created subclass
+  # @see Puppet::Util::ClassGen.genclass
+  #
+  # @dsl type
   # @api public
   def newtype(name, options = {}, &block)
     # Handle backward compatibility
@@ -97,7 +125,9 @@ def newtype(name, options = {}, &block)
     klass
   end
 
-  # Remove an existing defined type.  Largely used for testing.
+  # Removes an existing type.
+  # @note Only use this for testing.
+  # @api private
   def rmtype(name)
     # Then create the class.
 
@@ -106,7 +136,11 @@ def rmtype(name)
     singleton_class.send(:remove_method, "new#{name}") if respond_to?("new#{name}")
   end
 
-  # Return a Type instance by name.
+  # Returns a Type instance by name.
+  # This will load the type if not already defined.
+  # @param [String, Symbol] name of the wanted Type
+  # @return [Puppet::Type, nil] the type or nil if the type was not defined and could not be loaded
+  #
   def type(name)
     @types ||= {}
 
@@ -130,7 +164,10 @@ def type(name)
     return @types[name]
   end
 
-  # Create a loader for Puppet types.
+  # Creates a loader for Puppet types.
+  # Defaults to an instance of {Puppet::Util::Autoload} if no other auto loader has been set.
+  # @return [Puppet::Util::Autoload] the loader to use.
+  # @api private
   def typeloader
     unless defined?(@typeloader)
       @typeloader = Puppet::Util::Autoload.new(self, "puppet/type", :wrap => false)