puppet 3.0.2 → 3.1.0.rc1

data/lib/puppet/interface/face_collection.rb

@@ -3,14 +3,13 @@ require 'puppet/interface'
 module Puppet::Interface::FaceCollection
   @faces = Hash.new { |hash, key| hash[key] = {} }
 
+  @loader = Puppet::Util::Autoload.new(:application, 'puppet/face')
+
   def self.faces
     unless @loaded
       @loaded = true
-      $LOAD_PATH.each do |dir|
-        Dir.glob("#{dir}/puppet/face/*.rb").
-          collect {|f| File.basename(f, '.rb') }.
-          each {|name| self[name, :current] }
-      end
+      names = @loader.files_to_load.map {|fn| ::File.basename(fn, '.rb')}.uniq
+      names.each {|name| self[name, :current]}
     end
     @faces.keys.select {|name| @faces[name].length > 0 }
   end
@@ -58,7 +57,7 @@ module Puppet::Interface::FaceCollection
     # other Ruby library that we might want to use.  --daniel 2011-04-06
     if safely_require name then
       # If we wanted :current, we need to index to find that; direct version
-      # requests just work™ as they go. --daniel 2011-04-06
+      # requests just work as they go. --daniel 2011-04-06
       if version == :current then
         # We need to find current out of this.  This is the largest version
         # number that doesn't have a dedicated on-disk file present; those
@@ -99,7 +98,7 @@ module Puppet::Interface::FaceCollection
   end
 
   def self.safely_require(name, version = nil)
-    path = File.join 'puppet' ,'face', version.to_s, name.to_s
+    path = @loader.expand(version ? ::File.join(version.to_s, name.to_s) : name)
     require path
     true
 

data/lib/puppet/interface/option.rb

@@ -1,8 +1,15 @@
 require 'puppet/interface'
 
+# This represents an option on an action or face (to be globally applied
+# to its actions). Options should be constructed by calling
+# {Puppet::Interface::OptionManager#option}, which is available on
+# {Puppet::Interface}, and then calling methods of
+# {Puppet::Interface::OptionBuilder} in the supplied block.
+# @api public
 class Puppet::Interface::Option
   include Puppet::Interface::TinyDocs
 
+  # @api private
   def initialize(parent, *declaration, &block)
     @parent   = parent
     @optparse = []
@@ -69,18 +76,20 @@ class Puppet::Interface::Option
   # to_s and optparse_to_name are roughly mirrored, because they are used to
   # transform options to name symbols, and vice-versa.  This isn't a full
   # bidirectional transformation though. --daniel 2011-04-07
+
   def to_s
     @name.to_s.tr('_', '-')
   end
 
+  # @api private
   def optparse_to_optionname(declaration)
     unless found = declaration.match(/^-+(?:\[no-\])?([^ =]+)/) then
       raise ArgumentError, "Can't find a name in the declaration #{declaration.inspect}"
     end
     name = found.captures.first
   end
-    
 
+  # @api private
   def optparse_to_name(declaration)
     name = optparse_to_optionname(declaration).tr('-', '_')
     raise "#{name.inspect} is an invalid option name" unless name.to_s =~ /^[a-z]\w*$/

data/lib/puppet/interface/option_builder.rb

@@ -1,13 +1,19 @@
 require 'puppet/interface/option'
 
+# @api public
 class Puppet::Interface::OptionBuilder
+  # The option under construction
+  # @return [Puppet::Interface::Option]
+  # @api private
   attr_reader :option
 
+  # Build an option
+  # @return [Puppet::Interface::Option]
+  # @api private
   def self.build(face, *declaration, &block)
     new(face, *declaration, &block).option
   end
 
-  private
   def initialize(face, *declaration, &block)
     @face   = face
     @option = Puppet::Interface::Option.new(face, *declaration)
@@ -26,6 +32,15 @@ class Puppet::Interface::OptionBuilder
   end
 
   # Override some methods that deal in blocks, not objects.
+
+  # Sets a block to be executed when an action is invoked before the
+  # main action code. This is most commonly used to validate an option.
+  # @yieldparam action [Puppet::Interface::Action] The action being
+  #   invoked
+  # @yieldparam args [Array] The arguments given to the action
+  # @yieldparam options [Hash<Symbol=>Object>] Any options set
+  # @api public
+  # @dsl Faces
   def before_action(&block)
     block or raise ArgumentError, "#{@option} before_action requires a block"
     if @option.before_action
@@ -37,6 +52,10 @@ class Puppet::Interface::OptionBuilder
     @option.before_action = block
   end
 
+  # Sets a block to be executed after an action is invoked.
+  # !(see before_action)
+  # @api public
+  # @dsl Faces
   def after_action(&block)
     block or raise ArgumentError, "#{@option} after_action requires a block"
     if @option.after_action
@@ -48,10 +67,19 @@ class Puppet::Interface::OptionBuilder
     @option.after_action = block
   end
 
+  # Sets whether the option is required. If no argument is given it
+  # defaults to setting it as a required option.
+  # @api public
+  # @dsl Faces
   def required(value = true)
     @option.required = value
   end
 
+  # Sets a block that will be used to compute the default value for this
+  # option. It will be evaluated when the action is invoked. The block
+  # should take no arguments.
+  # @api public
+  # @dsl Faces
   def default_to(&block)
     block or raise ArgumentError, "#{@option} default_to requires a block"
     if @option.has_default?

data/lib/puppet/interface/option_manager.rb

@@ -1,7 +1,13 @@
 require 'puppet/interface/option_builder'
 
+# This class is not actually public API, but the method
+# {Puppet::Interface::OptionManager#option option} is public when used
+# as part of the Faces DSL (i.e. from within a
+# {Puppet::Interface.define define} block).
+# @api public
 module Puppet::Interface::OptionManager
-  
+
+  # @api private
   def display_global_options(*args)
     @display_global_options ||= []
     [args].flatten.each do |refopt|
@@ -12,11 +18,12 @@ module Puppet::Interface::OptionManager
     @display_global_options
   end
   alias :display_global_option :display_global_options
-  
+
   def all_display_global_options
     walk_inheritance_tree(@display_global_options, :all_display_global_options)
   end
-  
+
+  # @api private
   def walk_inheritance_tree(start, sym)
     result = (start ||= [])
     if self.is_a?(Class) and superclass.respond_to?(sym)
@@ -26,13 +33,18 @@ module Puppet::Interface::OptionManager
     end
     return result
   end
-  
-  # Declare that this app can take a specific option, and provide
-  # the code to do so.
+
+  # Declare that this app can take a specific option, and provide the
+  # code to do so. See {Puppet::Interface::ActionBuilder#option} for
+  # details.
+  #
+  # @api public
+  # @dsl Faces
   def option(*declaration, &block)
     add_option Puppet::Interface::OptionBuilder.build(self, *declaration, &block)
   end
 
+  # @api private
   def add_option(option)
     # @options collects the added options in the order they're declared.
     # @options_hash collects the options keyed by alias for quick lookups.
@@ -61,10 +73,12 @@ module Puppet::Interface::OptionManager
     return option
   end
 
+  # @api private
   def options
     walk_inheritance_tree(@options, :options)
   end
 
+  # @api private
   def get_option(name, with_inherited_options = true)
     @options_hash ||= {}
 
@@ -80,6 +94,7 @@ module Puppet::Interface::OptionManager
     return result
   end
 
+  # @api private
   def option?(name)
     options.include? name.to_sym
   end

data/lib/puppet/metatype/manager.rb

@@ -2,20 +2,29 @@ require 'puppet'
 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,32 @@ module Manager
     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
     unless options.is_a?(Hash)
@@ -96,7 +125,9 @@ module Manager
     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.
 
@@ -105,7 +136,11 @@ module Manager
     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 ||= {}
 
@@ -129,7 +164,10 @@ module Manager
     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)

data/lib/puppet/module_tool.rb

@@ -4,7 +4,6 @@ require 'pathname'
 require 'fileutils'
 require 'puppet/util/colors'
 
-# Define tool
 module Puppet
   module ModuleTool
     extend Puppet::Util::Colors

data/lib/puppet/network/formats.rb

@@ -101,8 +101,6 @@ Puppet::Network::FormatHandler.create(:raw, :mime => "application/x-raw", :weigh
 end
 
 Puppet::Network::FormatHandler.create_serialized_formats(:pson, :weight => 10, :required_methods => [:render_method, :intern_method]) do
-  confine :true => Puppet.features.pson?
-
   def intern(klass, text)
     data_to_instance(klass, PSON.parse(text))
   end

data/lib/puppet/node.rb

@@ -18,9 +18,8 @@ class Puppet::Node
 
   attr_accessor :name, :classes, :source, :ipaddress, :parameters
   attr_reader :time, :facts
-  #
-  # Load json before trying to register.
-  Puppet.features.pson? and ::PSON.register_document_type('Node',self)
+
+  ::PSON.register_document_type('Node',self)
 
   def self.from_pson(pson)
     raise ArgumentError, "No name provided in pson data" unless name = pson['name']

data/lib/puppet/node/environment.rb

@@ -1,7 +1,9 @@
 require 'puppet/util'
 require 'puppet/util/cacher'
+require 'puppet/util/manifest_filetype_helper'
 require 'monitor'
 
+
 # Just define it, so this class has fewer load dependencies.
 class Puppet::Node
 end
@@ -88,6 +90,17 @@ class Puppet::Node::Environment
     }
   end
 
+  # Yields each modules' plugin directory.
+  #
+  # @yield [String] Yields the plugin directory from each module to the block.
+  # @api public
+  def each_plugin_directory(&block)
+    modules.map(&:plugin_directory).each do |lib|
+      lib = Puppet::Util::Autoload.cleanpath(lib)
+      yield lib if File.directory?(lib)
+    end
+  end
+
   def module(name)
     modules.find {|mod| mod.name == name}
   end
@@ -205,7 +218,7 @@ class Puppet::Node::Environment
   private
 
   def perform_initial_import
-    return empty_parse_result if Puppet.settings[:ignoreimport]
+    return empty_parse_result if Puppet.settings[:ignoreimport] or Puppet::Util::ManifestFiletypeHelper.is_ruby_filename?(Puppet.settings.value(:manifest, name))
     parser = Puppet::Parser::Parser.new(self)
     if code = Puppet.settings.uninterpolated_value(:code, name.to_s) and code != ""
       parser.string = code

data/lib/puppet/parameter.rb

@@ -3,6 +3,22 @@ require 'puppet/util/log_paths'
 require 'puppet/util/logging'
 require 'puppet/util/docs'
 
+# The Parameter class is the implementation of a resource's attributes of _parameter_ kind.
+# The Parameter class is also the base class for {Puppet::Property}, and is used to describe meta-parameters
+# (parameters that apply to all resource types).
+# A Parameter (in contrast to a Property) has a single value where a property has both a current and a wanted value.
+# The Parameter class methods are used to configure and create an instance of Parameter that represents
+# one particular attribute data type; its valid value(s), and conversion to/from internal form.
+#
+# The intention is that a new parameter is created by using the DSL method {Puppet::Type.newparam}, or
+# {Puppet::Type.newmetaparam} if the parameter should be applicable to all resource types.
+#
+# A Parameter that does not specify and valid values (via {newvalues}) accepts any value.
+#
+# @see Puppet::Type
+# @see Puppet::Property
+# @api public
+# 
 class Puppet::Parameter
   include Puppet::Util
   include Puppet::Util::Errors
@@ -15,12 +31,71 @@ class Puppet::Parameter
   class << self
     include Puppet::Util
     include Puppet::Util::Docs
-    attr_reader :validater, :munger, :name, :default, :required_features, :value_collection
+    # Unused?
+    # @todo The term "validater" only appears in this location in the Puppet code base. There is `validate`
+    #   which seems to works fine without this attribute declaration.
+    # @api private
+    #
+    attr_reader :validater 
+
+    # Unused?
+    # @todo The term "munger" only appears in this location in the Puppet code base. There is munge and unmunge
+    #  and they seem to work perfectly fine without this attribute declaration.
+    # @api private
+    #
+    attr_reader :munger
+    
+    # @return [Symbol] The parameter name as given when it was created.
+    attr_reader :name
+    
+    # @return [Object] The default value of the parameter as determined by the {defaultto} method, or nil if no
+    #  default has been set.
+    attr_reader :default
+    
+    # @comment This somewhat odd documentation construct is because the getter and setter are not
+    #  orthogonal; the setter uses varargs and this confuses yard. To overcome the problem both the
+    #  getter and the setter are documented here. If this issues is fixed, a todo will be displayed
+    #  for the setter method, and the setter documentation can be moved there.
+    #  Since the attribute is actually RW it should  perhaps instead just be implemented as a setter
+    #  and a getter method (and no attr_xxx declaration).
+    #
+    # @!attribute [rw] required_features
+    # @return [Array<Symbol>] The names of the _provider features_ required for this parameter to work.
+    #   the returned names are always all lower case symbols.
+    # @overload required_features
+    #   Returns the required _provider features_ as an array of lower case symbols
+    # @overload required_features=(*args)
+    #   @param *args [Symbol] one or more names of required provider features 
+    #   Sets the required_provider_features_ from one or more values, or array. The given arguments
+    #   are flattened, and internalized.
+    # @api public
+    # @dsl type
+    #
+    attr_reader :required_features
+    
+    # @return [Puppet::Parameter::ValueCollection] The set of valid values (or an empty set that accepts any value).
+    # @api private
+    #
+    attr_reader :value_collection
+    
+    # @return [Boolean] Flag indicating whether this parameter is a meta-parameter or not.
     attr_accessor :metaparam
 
-    # Define the default value for a given parameter or parameter.  This
-    # means that 'nil' is an invalid default value.  This defines
-    # the 'default' instance method.
+    # Defines how the `default` value of a parameter is computed.
+    # The computation of the parameter's default value is defined by providing a value or a block. 
+    # A default of `nil` can not be used.
+    # @overload defaultto(value)
+    #   Defines the default value with a literal value
+    #   @param value [Object] the literal value to use as the default value
+    # @overload defaultto({|| ... })
+    #   Defines that the default value is produced by the given block. The given block
+    #   should produce the default value.
+    # @raise [Puppet::DevError] if value is nil, and no block is given.
+    # @return [void]
+    # @see Parameter.default
+    # @dsl type
+    # @api public
+    # 
     def defaultto(value = nil, &block)
       if block
         define_method(:default, &block)
@@ -33,8 +108,12 @@ class Puppet::Parameter
       end
     end
 
-    # Return a documentation string.  If there are valid values,
-    # then tack them onto the string.
+    # Produces a documentation string. 
+    # If an enumeration of _valid values_ has been defined, it is appended to the documentation
+    # for this parameter specified with the {desc} method.
+    # @return [String] Returns a documentation string.
+    # @api public
+    #
     def doc
       @doc ||= ""
 
@@ -50,21 +129,49 @@ class Puppet::Parameter
       @doc
     end
 
+    # Removes the `default` method if defined.
+    # Has no effect if the default method is not defined.
+    # This method is intended to be used in a DSL scenario where a parameter inherits from a parameter
+    # with a default value that is not wanted in the derived parameter (otherwise, simply do not define
+    # a default value method).
+    #
+    # @return [void]
+    # @see desc
+    # @api public
+    # @dsl type
+    #
     def nodefault
       undef_method :default if public_method_defined? :default
     end
 
-    # Store documentation for this parameter.
+    # Sets the documentation for this parameter.
+    # @param str [String] The documentation string to set
+    # @return [String] the given `str` parameter
+    # @see doc
+    # @dsl type
+    # @api public
+    #
     def desc(str)
       @doc = str
     end
 
+    # Initializes the instance variables.
+    # Clears the internal value collection (set of allowed values).
+    # @return [void]
+    # @api private
+    #
     def initvars
       @value_collection = ValueCollection.new
     end
 
-    # This is how we munge the value.  Basically, this is our
-    # opportunity to convert the value from one form into another.
+    # @overload munge {|| ... }
+    # Defines an optional method used to convert the parameter value from DSL/string form to an internal form.
+    # If a munge method is not defined, the DSL/string value is used as is.
+    # @note This adds a method with the name `unsafe_munge` in the created parameter class. Later this method is
+    #   called in a context where exceptions will be rescued and handled.
+    # @dsl type
+    # @api public
+    #
     def munge(&block)
       # I need to wrap the unsafe version in begin/rescue parameterments,
       # but if I directly call the block then it gets bound to the
@@ -73,55 +180,105 @@ class Puppet::Parameter
       define_method(:unsafe_munge, &block)
     end
 
-    # Does the parameter support reverse munging?
-    # This will be called when something wants to access the parameter
-    # in a canonical form different to what the storage form is.
+    # @overload unmunge {|| ... }
+    # Defines an optional method used to convert the parameter value to DSL/string form from an internal form.
+    # If an `unmunge` method is not defined, the internal form is used.
+    # @see munge
+    # @note This adds a method with the name `unmunge` in the created parameter class.
+    # @dsl type
+    # @api public
+    #
     def unmunge(&block)
       define_method(:unmunge, &block)
     end
 
-    # Mark whether we're the namevar.
+    # Sets a marker indicating that this parameter is the _namevar_ (unique identifier) of the type
+    # where the parameter is contained.
+    # This also makes the parameter a required value. The marker can not be unset once it has been set.
+    # @return [void]
+    # @dsl type
+    # @api public
+    #
     def isnamevar
       @isnamevar = true
       @required = true
     end
 
-    # Is this parameter the namevar?  Defaults to false.
+    # @return [Boolean] Returns whether this parameter is the _namevar_ or not.
+    # @api public
+    #
     def isnamevar?
       @isnamevar
     end
 
-    # This parameter is required.
+    # Sets a marker indicating that this parameter is required.
+    # Once set, it is not possible to make a parameter optional.
+    # @return [void]
+    # @dsl type
+    # @api public
+    #
     def isrequired
       @required = true
     end
 
-    # Specify features that are required for this parameter to work.
+    # @comment This method is not picked up by yard as it has a different signature than
+    #   expected for an attribute (varargs). Instead, this method is documented as an overload
+    #   of the attribute required_features. (Not ideal, but better than nothing).
+    # @todo If this text appears in documentation - see comment in source and makes corrections - it means
+    #   that an issue in yardoc has been fixed.
+    #
     def required_features=(*args)
       @required_features = args.flatten.collect { |a| a.to_s.downcase.intern }
     end
 
-    # Is this parameter required?  Defaults to false.
+    # Returns whether this parameter is required or not.
+    # A parameter is required if a call has been made to the DSL method {isrequired}.
+    # @return [Boolean] Returns whether this parameter is required or not.
+    # @api public
+    #
     def required?
       @required
     end
 
-    # Verify that we got a good value
+    # @overload validate {|| ... }
+    # Defines an optional method that is used to validate the parameter's value.
+    # Validation should raise appropriate exceptions, the return value of the given block is ignored.
+    # @return [void]
+    # @dsl type
+    # @api public
+    #
     def validate(&block)
       define_method(:unsafe_validate, &block)
     end
 
-    # Define a new value for our parameter.
+    # Defines valid values for the parameter (enumeration or regular expressions).
+    # The set of valid values for the parameter can be limited to a (mix of) literal values and
+    # regular expression patterns.
+    # @note Each call to this method adds to the set of valid values
+    # @param names [Symbol, Regexp] The set of valid literal values and/or patterns for the parameter.
+    # @return [void] 
+    # @dsl type
+    # @api public
+    #
     def newvalues(*names)
       @value_collection.newvalues(*names)
     end
 
+    # Makes the given `name` an alias for the given `other` name.
+    # Or said differently, the valid value `other` can now also be referred to via the given `name`.
+    # Aliasing may affect how the parameter's value is serialized/stored (it may store the `other` value
+    # instead of the alias).
+    # @api public
+    # @dsl type
+    #
     def aliasvalue(name, other)
       @value_collection.aliasvalue(name, other)
     end
   end
 
-  # Just a simple method to proxy instance methods to class methods
+  # Creates instance (proxy) methods that delegates to a class method with the same name.
+  # @api private
+  #
   def self.proxymethods(*values)
     values.each { |val|
       define_method(val) do
@@ -130,21 +287,45 @@ class Puppet::Parameter
     }
   end
 
-  # And then define one of these proxies for each method in our
-  # ParamHandler class.
+  # @!method required?
+  #   (see required?)
+  # @!method isnamevar?
+  #   (see isnamevar?)
+  #
   proxymethods("required?", "isnamevar?")
 
+  # @return [Puppet::Resource] A reference to the resource this parameter is an attribute of (the _associated resource_).
   attr_accessor :resource
-  # LAK 2007-05-09: Keep the @parent around for backward compatibility.
+
+  # @comment LAK 2007-05-09: Keep the @parent around for backward compatibility.
+  # @return [Puppet::Parameter] A reference to the parameter's parent kept for backwards compatibility.
+  # @api private
+  #
   attr_accessor :parent
 
+  # @!method line()
+  #   @return [Integer] Returns the result of calling the same method on the associated resource.
+  # @!method file
+  #   @return [Integer] Returns the result of calling the same method on the associated resource.
+  # @!method version
+  #   @return [Integer] Returns the result of calling the same method on the associated resource.
+  #
   [:line, :file, :version].each do |param|
     define_method(param) do
       resource.send(param)
     end
   end
 
-  # Basic parameter initialization.
+  # Initializes the parameter with a required resource reference and optional attribute settings.
+  # The option `:resource` must be specified or an exception is raised. Any additional options passed
+  # are used to initialize the attributes of this parameter by treating each key in the `options` hash as 
+  # the name of the attribute to set, and the value as the value to set.
+  # @param options [Hash{Symbol => Object]] Options, where `resource` is required
+  # @option options [Puppet::Resource] :resource The resource this parameter holds a value for. Required.
+  # @raise [Puppet::DevError] If resource is not specified in the options hash.
+  # @api public
+  # @note A parameter should be created via the DSL method {Puppet::Type::newparam}
+  # 
   def initialize(options = {})
     options = symbolize_options(options)
     if resource = options[:resource]
@@ -157,24 +338,35 @@ class Puppet::Parameter
     set_options(options)
   end
 
+  # Writes the given `msg` to the log with the loglevel indicated by the associated resource's 
+  # `loglevel` parameter.
+  # @todo is loglevel a metaparameter? it is looked up with `resource[:loglevel]`
+  # @return [void]
+  # @api public
   def log(msg)
     send_log(resource[:loglevel], msg)
   end
 
-  # Is this parameter a metaparam?
+  # @return [Boolean] Returns whether this parameter is a meta-parameter or not.
   def metaparam?
     self.class.metaparam
   end
 
-  # each parameter class must define the name method, and parameter
-  # instances do not change that name this implicitly means that a given
-  # object can only have one parameter instance of a given parameter
-  # class
+  # @!attribute [r] name
+  # @return [Symbol] The parameter's name as given when it was created.
+  # @note Since a Parameter defines the name at the class level, each Parameter class must be 
+  #  unique within a type's inheritance chain.
+  # @comment each parameter class must define the name method, and parameter
+  #   instances do not change that name this implicitly means that a given
+  #   object can only have one parameter instance of a given parameter
+  #   class
   def name
     self.class.name
   end
 
-  # for testing whether we should actually do anything
+  # @return [Boolean] Returns true if this parameter, the associated resource, or overall puppet mode is `noop`.
+  # @todo How is noop mode set for a parameter? Is this of value in DSL to inhibit a parameter?
+  # 
   def noop
     @noop ||= false
     tmp = @noop || self.resource.noop || Puppet[:noop] || false
@@ -182,8 +374,11 @@ class Puppet::Parameter
     tmp
   end
 
-  # return the full path to us, for logging and rollback; not currently
-  # used
+  # @todo Original comment = _return the full path to us, for logging and rollback; not currently
+  #   used_ This is difficult to figure out (if it is used or not as calls are certainly made to "pathbuilder"
+  #   method is several places, not just sure if it is this implementation or not.
+  # 
+  # @api private
   def pathbuilder
     if @resource
       return [@resource.pathbuilder, self.name]
@@ -192,18 +387,31 @@ class Puppet::Parameter
     end
   end
 
-  # If the specified value is allowed, then munge appropriately.
-  # If the developer uses a 'munge' hook, this method will get overridden.
+  # This is the default implementation of `munge` that simply produces the value (if it is valid).
+  # The DSL method {munge} should be used to define an overriding method if munging is required.
+  #
+  # @api private
+  #
   def unsafe_munge(value)
     self.class.value_collection.munge(value)
   end
 
-  # no unmunge by default
+  # Unmunges the value by transforming it from internal form to DSL form.
+  # This is the default implementation of `unmunge` that simply returns the value without processing.
+  # The DSL method {unmunge} should be used to define an overriding method if required.
+  # @return [Object] the unmunged value
+  #
   def unmunge(value)
     value
   end
 
-  # A wrapper around our munging that makes sure we raise useful exceptions.
+  # Munges the value to internal form.
+  # This implementation of `munge` provides exception handling around the specified munging of this parameter.
+  # @note This method should not be overridden. Use the DSL method {munge} to define a munging method
+  #   if required.
+  # @param value [Object] the DSL value to munge
+  # @return [Object] the munged (internal) value
+  #
   def munge(value)
     begin
       ret = unsafe_munge(value)
@@ -216,13 +424,27 @@ class Puppet::Parameter
     ret
   end
 
-  # Verify that the passed value is valid.
-  # If the developer uses a 'validate' hook, this method will get overridden.
+  # This is the default implementation of `validate` that may be overridden by the DSL method {validate}. 
+  # If no valid values have been defined, the given value is accepted, else it is validated against
+  # the literal values (enumerator) and/or patterns defined by calling {newvalues}.
+  #
+  # @param value [Object] the value to check for validity
+  # @raise [ArgumentError] if the value is not valid
+  # @return [void]
+  # @api private
+  # 
   def unsafe_validate(value)
     self.class.value_collection.validate(value)
   end
 
+  # Performs validation of the given value against the rules defined by this parameter.
+  # @return [void]
+  # @todo Better description of when the various exceptions are raised.ArgumentError is rescued and
+  #   changed into Puppet::Error.
+  # @raise [ArgumentError, TypeError, Puppet::DevError, Puppet::Error] under various conditions 
   # A protected validation method that only ever raises useful exceptions.
+  # @api public
+  #
   def validate(value)
     begin
       unsafe_validate(value)
@@ -235,30 +457,54 @@ class Puppet::Parameter
     end
   end
 
+  # Sets the associated resource to nil.
+  # @todo Why - what is the intent/purpose of this?
+  # @return [nil]
+  #
   def remove
     @resource = nil
   end
 
+  # @return [Object] Gets the value of this parameter after performing any specified unmunging.
   def value
     unmunge(@value) unless @value.nil?
   end
 
-  # Store the value provided.  All of the checking should possibly be
-  # late-binding (e.g., users might not exist when the value is assigned
-  # but might when it is asked for).
+  # Sets the given value as the value of this parameter.
+  # @todo This original comment _"All of the checking should possibly be
+  #   late-binding (e.g., users might not exist when the value is assigned
+  #   but might when it is asked for)."_ does not seem to be correct, the implementation
+  #   calls both validate an munge on the given value, so no late binding.
+  # 
+  # The given value is validated and then munged (if munging has been specified). The result is store
+  # as the value of this arameter.
+  # @return [Object] The given `value` after munging.
+  # @raise (see #validate)
+  #
   def value=(value)
     validate(value)
 
     @value = munge(value)
   end
 
-  # Retrieve the resource's provider.  Some types don't have providers, in which
-  # case we return the resource object itself.
+  # @return [Puppet::Provider] Returns the provider of the associated resource.
+  # @todo The original comment says = _"Retrieve the resource's provider.
+  #   Some types don't have providers, in which case we return the resource object itself."_
+  #   This does not seem to be true, the default implementation that sets this value may be
+  #   {Puppet::Type.provider=} which always gets either the name of a provider or an instance of one.
+  # 
   def provider
     @resource.provider
   end
 
-  # The properties need to return tags so that logs correctly collect them.
+  # @return [Array<Symbol>] Returns an array of the associated resource's symbolic tags (including the parameter itself).
+  # Returns an array of the associated resource's symbolic tags (including the parameter itself).
+  # At a minimun, the array contains the name of the parameter. If the associated resource
+  # has tags, these tags are also included in the array.
+  # @todo The original comment says = _"The properties need to return tags so that logs correctly
+  #   collect them."_ what if anything of that is of interest to document. Should tags and their relationship
+  #   to logs be described. This is a more general concept.
+  # 
   def tags
     unless defined?(@tags)
       @tags = []
@@ -269,10 +515,29 @@ class Puppet::Parameter
     @tags
   end
 
+  # @return [String] The name of the parameter in string form.
   def to_s
     name.to_s
   end
 
+  # Produces a String with the value formatted for display to a human.
+  # When the parameter value is a:
+  # 
+  # * **single valued parameter value** the result is produced on the
+  #   form `'value'` where _value_ is the string form of the parameter's value. 
+  #
+  # * **Array** the list of values is enclosed in `[]`, and 
+  #   each produced value is separated by a comma.
+  # 
+  # * **Hash** value is output with keys in sorted order enclosed in `{}` with each entry formatted
+  #   on the form `'k' => v` where
+  #   `k` is the key in string form and _v_ is the value of the key. Entries are comma separated.
+  #
+  # For both Array and Hash this method is called recursively to format contained values.
+  # @note this method does not protect against infinite structures.
+  # 
+  # @return [String] The formatted value in string form.
+  #
   def self.format_value_for_display(value)
     if value.is_a? Array
       formatted_values = value.collect {|value| format_value_for_display(value)}.join(', ')