puppet 3.0.2 → 3.1.0.rc1

data/lib/puppet/property/ensure.rb

@@ -1,7 +1,12 @@
 require 'puppet/property'
 
-# This property will get automatically added to any type that responds
+# This property is automatically added to any {Puppet::Type} that responds
 # to the methods 'exists?', 'create', and 'destroy'.
+#
+# Ensure defaults to having the wanted _(should)_ value `:present`.
+#
+# @api public
+#
 class Puppet::Property::Ensure < Puppet::Property
   @name = :ensure
 
@@ -58,6 +63,14 @@ class Puppet::Property::Ensure < Puppet::Property
     end
   end
 
+  # Retrieves the _is_ value for the ensure property.
+  # The existence of the resource is checked by first consulting the provider (if it responds to
+  # `:exists`), and secondly the resource. A a value of `:present` or `:absent` is returned
+  # depending on if the managed entity exists or not.
+  # 
+  # @return [Symbol] a value of `:present` or `:absent` depending on if it exists or not
+  # @raise [Puppet::DevError] if neither the provider nor the resource responds to `:exists`
+  # 
   def retrieve
     # XXX This is a problem -- whether the object exists or not often
     # depends on the results of other properties, yet we're the first property

data/lib/puppet/property/keyvalue.rb

@@ -1,15 +1,16 @@
-#This subclass of property manages string key value pairs.
-
-#In order to use this property:
-# - the @should value must be an array of keyvalue pairs separated by the 'separator'
-# - the retrieve method should return a hash with the keys as symbols
-# IMPORTANT NOTE: In order for this property to work there must also be a 'membership' parameter
-# The class that inherits from property should override that method with the symbol for the membership
-
 require 'puppet/property'
 
 module Puppet
   class Property
+    # This subclass of {Puppet::Property} manages string key value pairs.
+    # In order to use this property:
+    #
+    # * the _should_ value must be an array of key-value pairs separated by the 'separator'
+    # * the retrieve method should return a hash with the keys as symbols
+    # @note **IMPORTANT**: In order for this property to work there must also be a 'membership' parameter
+    #   The class that inherits from property should override that method with the symbol for the membership
+    # @todo The node with an important message is not very clear.
+    #
     class KeyValue < Property
 
       def hash_to_key_value_s(hash)
@@ -59,14 +60,19 @@ module Puppet
         current.merge(members)
       end
 
+      # @return [String] Returns a default separator of "="
       def separator
         "="
       end
 
+      # @return [String] Returns a default delimiter of ";"
       def delimiter
         ";"
       end
 
+      # Retrieves the key-hash from the provider by invoking it's method named the same as this property.
+      # @return [Hash] the hash from the provider, or `:absent`
+      #
       def retrieve
         #ok, some 'convention' if the keyvalue property is named properties, provider should implement a properties method
         if key_hash = provider.send(name) and key_hash != :absent
@@ -76,6 +82,9 @@ module Puppet
         end
       end
 
+      # Returns true if there is no _is_ value, else returns if _is_ is equal to _should_ using == as comparison.
+      # @return [Boolean] whether the property is in sync or not.
+      #
       def insync?(is)
         return true unless is
 

data/lib/puppet/property/list.rb

@@ -2,6 +2,9 @@ require 'puppet/property'
 
 module Puppet
   class Property
+    # This subclass of {Puppet::Property} manages an unordered list of values.
+    # For an ordered list see {Puppet::Property::OrderedList}.
+    #
     class List < Property
 
       def should_to_s(should_value)

data/lib/puppet/property/ordered_list.rb

@@ -2,6 +2,13 @@ require 'puppet/property/list'
 
 module Puppet
   class Property
+    # This subclass of {Puppet::Property} manages an ordered list of values.
+    # The maintained order is the order defined by the 'current' set of values (i.e. the
+    # original order is not disrupted). Any additions are added after the current values
+    # in their given order).
+    # 
+    # For an unordered list see {Puppet::Property::List}.
+    #
     class OrderedList < List
 
       def add_should_with_current(should, current)

data/lib/puppet/provider.rb

@@ -1,4 +1,40 @@
-# The container class for implementations.
+# A Provider is an implementation of the actions that manage resources (of some type) on a system.
+# This class is the base class for all implementation of a Puppet Provider.
+#
+# Concepts:
+#--
+# * **Confinement** - confinement restricts providers to only be applicable under certain conditions.
+#    It is possible to confine a provider several different ways:
+#    * the included {#confine} method which provides filtering on fact, feature, existence of files, or a free form
+#      predicate.
+#    * the {commands} method that filters on the availability of given system commands.
+# * **Property hash** - the important instance variable `@property_hash` contains all current state values
+#   for properties (it is lazily built). It is important that these values are managed appropriately in the
+#   methods {instances}, {prefetch}, and in methods that alters the current state (those that change the
+#   lifecycle (creates, destroys), or alters some value reflected backed by a property).
+# * **Flush** - is a hook that is called once per resource when everything has been applied. The intent is
+#   that an implementation may defer modification of the current state typically done in property setters
+#   and instead record information that allows flush to perform the changes more efficiently.  
+# * **Execution Methods** -  The execution methods provides access to execution of arbitrary commands.
+#   As a convenience execution methods are available on both the instance and the class of a provider since a
+#   lot of provider logic switch between these contexts fairly freely.
+# * **System Entity/Resource** - this documentation uses the term "system entity" for system resources to make
+#   it clear if talking about a resource on the system being managed (e.g. a file in the file system)
+#   or about a description of such a resource (e.g. a Puppet Resource).
+# * **Resource Type** - this is an instance of Type that describes a classification of instances of Resource (e.g.
+#   the `File` resource type describes all instances of `file` resources).
+#   (The term is used to contrast with "type" in general, and specifically to contrast with the implementation
+#   class of Resource or a specific Type).
+#
+# @note An instance of a Provider is associated with one resource.
+#
+# @note Class level methods are only called once to configure the provider (when the type is created), and not
+#   for each resource the provider is operating on.
+#   The instance methods are however called for each resource. 
+# 
+#
+# @api public
+#
 class Puppet::Provider
   include Puppet::Util
   include Puppet::Util::Errors
@@ -16,53 +52,105 @@ class Puppet::Provider
     # Include the util module so we have access to things like 'which'
     include Puppet::Util, Puppet::Util::Docs
     include Puppet::Util::Logging
+    
+    # @return [String] The name of the provider
     attr_accessor :name
 
-    # The source parameter exists so that providers using the same
-    # source can specify this, so reading doesn't attempt to read the
-    # same package multiple times.
+    # 
+    # @todo Original = _"The source parameter exists so that providers using the same
+    #   source can specify this, so reading doesn't attempt to read the
+    #   same package multiple times."_ This seems to be a package type specific attribute. Is this really
+    #   used?
+    #
+    # @return [???] The source is WHAT?
     attr_writer :source
 
-    # LAK 2007-05-09: Keep the model stuff around for backward compatibility
+    # @todo Original = _"LAK 2007-05-09: Keep the model stuff around for backward compatibility"_
+    #   Is this really needed? The comment about backwards compatibility was made in 2007.
+    #
+    # @return [???] A model kept for backwards compatibility.
+    # @api private
+    # @deprecated This attribute is available for backwards compatibility reasons.
     attr_reader :model
+    
+    # @todo What is this type? A reference to a Puppet::Type ?
+    # @return [Puppet::Type] the resource type (that this provider is ... WHAT?)
+    #
     attr_accessor :resource_type
+    
+    # @!attribute [r] doc
+    #   The (full) documentation for this provider class. The documentation for the provider class itself
+    #   should be set with the DSL method {desc=}. Setting the documentation with with {doc=} has the same effect
+    #   as setting it with {desc=} (only the class documentation part is set). In essence this means that
+    #   there is no getter for the class documentation part (since the getter returns the full
+    #   documentation when there are additional contributors).
+    #   
+    #   @return [String] Returns the full documentation for the provider.
+    # @see Puppet::Utils::Docs
+    # @comment This is puzzling ... a write only doc attribute??? The generated setter never seems to be
+    #   used, instead the instance variable @doc is set in the `desc` method. This seems wrong. It is instead
+    #   documented as a read only attribute (to get the full documentation). Also see doc below for
+    #   desc.
+    # @!attribute [w] desc
+    #   Sets the documentation of this provider class. (The full documentation is read via the
+    #   {doc} attribute).
+    #
+    #   @dsl type
+    # 
+    #
     attr_writer :doc
+    
   end
 
-  # LAK 2007-05-09: Keep the model stuff around for backward compatibility
+  # @todo original = _"LAK 2007-05-09: Keep the model stuff around for backward compatibility"_, why is it
+  #   both here (instance) and at class level? Is this a different model?
+  # @return [???] model is WHAT?
   attr_reader :model
+  
+  # @return [???] This resource is what? Is an instance of a provider attached to one particular Puppet::Resource?
+  #
   attr_accessor :resource
 
-  # Provide access to execution of arbitrary commands in providers. Execution methods are
-  # available on both the instance and the class of a provider because it seems that a lot of
-  # providers switch between these contexts fairly freely.
-  #
-  # @see Puppet::Util::Execution for how to use these methods
+  # Convenience methods - see class method with the same name.
+  # @see execute
+  # @return (see execute)
   def execute(*args)
     Puppet::Util::Execution.execute(*args)
   end
 
+  # (see Puppet::Util::Execution.execute)
   def self.execute(*args)
     Puppet::Util::Execution.execute(*args)
   end
 
+  # Convenience methods - see class method with the same name.
+  # @see execpipe
+  # @return (see execpipe)
   def execpipe(*args, &block)
     Puppet::Util::Execution.execpipe(*args, &block)
   end
 
+  # (see Puppet::Util::Execution.execpipe)
   def self.execpipe(*args, &block)
     Puppet::Util::Execution.execpipe(*args, &block)
   end
 
+  # Convenience methods - see class method with the same name.
+  # @see execfail
+  # @return (see execfail)
   def execfail(*args)
     Puppet::Util::Execution.execfail(*args)
   end
 
+  # (see Puppet::Util::Execution.execfail)
   def self.execfail(*args)
     Puppet::Util::Execution.execfail(*args)
   end
-  #########
 
+  # Returns the absolute path to the executable for the command referenced by the given name.
+  # @raise [Puppet::DevError] if the name does not reference an existing command.
+  # @return [String] the absolute path to the found executable for the command
+  # @see which
   def self.command(name)
     name = name.intern
 
@@ -77,22 +165,33 @@ class Puppet::Provider
     which(command)
   end
 
-  # Define commands that are not optional.
+  # Confines this provider to be suitable only on hosts where the given commands are present.
+  # Also see {Puppet::Provider::Confiner#confine} for other types of confinement of a provider by use of other types of
+  # predicates.
+  # 
+  # @note It is preferred if the commands are not entered with absolute paths as this allows puppet
+  #   to search for them using the PATH variable.
   #
-  # @param [Hash{String => String}] command_specs Named commands that the provider will 
+  # @param command_specs [Hash{String => String}] Map of name to command that the provider will 
   #   be executing on the system. Each command is specified with a name and the path of the executable.
-  # (@see #has_command)
+  # @return [void]
+  # @see optional_commands
+  #
   def self.commands(command_specs)
     command_specs.each do |name, path|
       has_command(name, path)
     end
   end
 
-  # Define commands that are optional.
-  #
+  # Defines optional commands.
+  # Since Puppet 2.7.8 this is typically not needed as evaluation of provider suitability
+  # is lazy (when a resource is evaluated) and the absence of commands
+  # that will be present after other resources have been applied no longer needs to be specified as
+  # optional.
   # @param [Hash{String => String}] command_specs Named commands that the provider will 
   #   be executing on the system. Each command is specified with a name and the path of the executable.
   # (@see #has_command)
+  # @see commands
   def self.optional_commands(hash)
     hash.each do |name, target|
       has_command(name, target) do
@@ -101,27 +200,31 @@ class Puppet::Provider
     end
   end
 
-  # Define a single command
-  #
-  # A method will be generated on the provider that allows easy execution of the command. The generated 
-  # method can take arguments that will be passed through to the executable as the command line arguments 
-  # when it is run.
+  # Creates a convenience method for invocation of a command.
   #
-  #     has_command(:echo, "/bin/echo")
-  #     def some_method
-  #       echo("arg 1", "arg 2")
-  #     end
+  # This generates a Provider method that allows easy execution of the command. The generated 
+  # method may take arguments that will be passed through to the executable as the command line arguments 
+  # when it is invoked.
   #
-  #     # or
+  # @example Use it like this:
+  #   has_command(:echo, "/bin/echo")
+  #   def some_method
+  #     echo("arg 1", "arg 2")
+  #   end
+  # @comment the . . .  below is intentional to avoid the three dots to become an illegible ellipsis char.
+  # @example . . . or like this
+  #   has_command(:echo, "/bin/echo") do
+  #     is_optional
+  #     environment :HOME => "/var/tmp", :PWD => "/tmp"
+  #   end
   #
-  #     has_command(:echo, "/bin/echo") do
-  #       is_optional
-  #       environment :HOME => "/var/tmp", :PWD => "/tmp"
-  #     end
+  # @param name [Symbol] The name of the command (will become the name of the generated method that executes the command)
+  # @param path [String] The path to the executable for the command
+  # @yield [ ] A block that configures the command (see {Puppet::Provider::Command})
+  # @comment a yield [ ] produces {|| ...} in the signature, do not remove the space.
+  # @note the name ´has_command´ looks odd in an API context, but makes more sense when seen in the internal
+  #   DSL context where a Provider is declaratively defined. 
   #
-  # @param [Symbol] name Name of the command (will be the name of the generated method to call the command)
-  # @param [String] path The path to the executable for the command
-  # @yield A block that configures the command (@see Puppet::Provider::Command) 
   def self.has_command(name, path, &block)
     name = name.intern
     command = CommandDefiner.define(name, path, self, &block)
@@ -134,6 +237,8 @@ class Puppet::Provider
     end
   end
 
+  # Internal helper class when creating commands - undocumented.
+  # @api private
   class CommandDefiner
     private_class_method :new
 
@@ -168,13 +273,15 @@ class Puppet::Provider
     end
   end
 
-  # Is the provided feature a declared feature?
+  # @return [Boolean] Return whether the given feature has been declared or not.
   def self.declared_feature?(name)
     defined?(@declared_features) and @declared_features.include?(name)
   end
 
-  # Does this implementation match all of the default requirements?  If
-  # defaults are empty, we return false.
+  # @return [Boolean] Returns whether this implementation satisfies all of the default requirements or not.
+  #   Returns false If defaults are empty.
+  # @see Provider.defaultfor
+  #
   def self.default?
     return false if @defaults.empty?
     if @defaults.find do |fact, values|
@@ -198,31 +305,79 @@ class Puppet::Provider
     end
   end
 
-  # Store how to determine defaults.
+  # Sets a facts filter that determine which of several suitable providers should be picked by default.
+  # This selection only kicks in if there is more than one suitable provider.
+  # To filter on multiple facts the given hash may contain more than one fact name/value entry.
+  # The filter picks the provider if all the fact/value entries match the current set of facts. (In case
+  # there are still more than one provider after this filtering, the first found is picked).
+  # @param hash [Hash<{String => Object}>] hash of fact name to fact value.
+  # @return [void]
+  #
   def self.defaultfor(hash)
     hash.each do |d,v|
       @defaults[d] = v
     end
   end
 
+  # @return [Integer] Returns a numeric specificity for this provider based on how many requirements it has
+  #  and number of _ancestors_. The higher the number the more specific the provider.
+  # The number of requirements is based on the number of defaults set up with {Provider.defaultfor}.
+  #
+  # The _ancestors_ is the Ruby Module::ancestors method and the number of classes returned is used
+  # to boost the score. The intent is that if two providers are equal, but one is more "derived" than the other
+  # (i.e. includes more classes), it should win because it is more specific). 
+  # @note Because of how this value is
+  #   calculated there could be surprising side effects if a provider included an excessive amount of classes. 
+  #
   def self.specificity
+    # This strange piece of logic attempts to figure out how many parent providers there
+    # are to increase the score. What is will actually do is count all classes that Ruby Module::ancestors
+    # returns (which can be other classes than those the parent chain) - in a way, an odd measure of the
+    # complexity of a provider).
     (@defaults.length * 100) + ancestors.select { |a| a.is_a? Class }.length
   end
 
+  # Initializes defaults and commands (i.e. clears them).
+  # @return [void]
   def self.initvars
     @defaults = {}
     @commands = {}
   end
 
-  # The method for returning a list of provider instances.  Note that it returns providers, preferably with values already
-  # filled in, not resources.
+  # Returns a list of system resources (entities) this provider may/can manage.
+  # This is a query mechanism that lists entities that the provider may manage on a given system. It is
+  # is directly used in query services, but is also the foundation for other services; prefetching, and
+  # purging.
+  #
+  # As an example, a package provider lists all installed packages. (In contrast, the File provider does
+  # not list all files on the file-system as that would make execution incredibly slow). An implementation
+  # of this method should be made if it is possible to quickly (with a single system call) provide all
+  # instances.
+  #
+  # An implementation of this method should only cache the values of properties
+  # if they are discovered as part of the process for finding existing resources.
+  # Resource properties that require additional commands (than those used to determine existence/identity) 
+  # should be implemented in their respective getter method. (This is important from a performance perspective;
+  # it may be expensive to compute, as well as wasteful as all discovered resources may perhaps not be managed). 
+  #
+  # An implementation may return an empty list (naturally with the effect that it is not possible to query
+  # for manageable entities).
+  #
+  # By implementing this method, it is possible to use the `resources´ resource type to specify purging
+  # of all non managed entities.
+  #
+  # @note The returned instances are instance of some subclass of Provider, not resources.
+  # @return [Array<Puppet::Provider>] a list of providers referencing the system entities
+  # @abstract this method must be implemented by a subclass and this super method should never be called as it raises an exception.
+  # @raise [Puppet::DevError] Error indicating that the method should have been implemented by subclass.
+  # @see prefetch 
   def self.instances
     raise Puppet::DevError, "Provider #{self.name} has not defined the 'instances' class method"
   end
 
-  # Create the methods for a given command.
-  #
-  # @deprecated Use {#commands}, {#optional_commands}, or {#has_command} instead. This was not meant to be part of a public API
+  # Creates the methods for a given command.
+  # @api private
+  # @deprecated Use {commands}, {optional_commands}, or {has_command} instead. This was not meant to be part of a public API
   def self.make_command_methods(name)
     Puppet.deprecation_warning "Provider.make_command_methods is deprecated; use Provider.commands or Provider.optional_commands instead for creating command methods"
 
@@ -245,9 +400,19 @@ class Puppet::Provider
     end
   end
 
-  # Create getter/setter methods for each property our resource type supports.
-  # They all get stored in @property_hash.  This method is useful
-  # for those providers that use prefetch and flush.
+  # Creates getter- and setter- methods for each property supported by the resource type.
+  # Call this method to generate simple accessors for all properties supported by the
+  # resource type. These simple accessors lookup and sets values in the property hash.
+  # The generated methods may be overridden by more advanced implementations if something
+  # else than a straight forward getter/setter pair of methods is required.
+  # (i.e. define such overriding methods after this method has been called)
+  # 
+  # An implementor of a provider that makes use of `prefetch` and `flush` can use this method since it uses
+  # the internal `@property_hash` variable to store values. An implementation would then update the system
+  # state on a call to `flush` based on the current values in the `@property_hash`.
+  #
+  # @return [void]
+  #
   def self.mk_resource_methods
     [resource_type.validproperties, resource_type.parameters].flatten.each do |attr|
       attr = attr.intern
@@ -264,6 +429,10 @@ class Puppet::Provider
 
   self.initvars
 
+  # This method is used to generate a method for a command.
+  # @return [void]
+  # @api private
+  #
   def self.create_class_and_instance_method(name, &block)
     unless singleton_class.method_defined?(name)
       meta_def(name, &block)
@@ -277,12 +446,20 @@ class Puppet::Provider
   end
   private_class_method :create_class_and_instance_method
 
-  # Retrieve the data source.  Defaults to the provider name.
+  # @return [String] Returns the data source, which is the provider name if no other source has been set.
+  # @todo Unclear what "the source" is used for? 
   def self.source
     @source ||= self.name
   end
 
-  # Does this provider support the specified parameter?
+  # Returns true if the given attribute/parameter is supported by the provider.
+  # The check is made that the parameter is a valid parameter for the resource type, and then
+  # if all its required features (if any) are supported by the provider.
+  #
+  # @param param [Class, Puppet::Parameter] the parameter class, or a parameter instance
+  # @return [Boolean] Returns whether this provider supports the given parameter or not.
+  # @raise [Puppet::DevError] if the given parameter is not valid for the resource type
+  #
   def self.supports_parameter?(param)
     if param.is_a?(Class)
       klass = param
@@ -331,22 +508,34 @@ class Puppet::Provider
     end
   end
 
-  # Remove the reference to the resource, so GC can clean up.
+  # Clears this provider instance to allow GC to clean up. 
   def clear
     @resource = nil
     @model = nil
   end
 
-  # Retrieve a named command.
+  # (see command)
   def command(name)
     self.class.command(name)
   end
 
-  # Get a parameter value.
+  # Returns the value of a parameter value, or `:absent` if it is not defined.
+  # @param param [Puppet::Parameter] the parameter to obtain the value of
+  # @return [Object] the value of the parameter or `:absent` if not defined.
+  #
   def get(param)
     @property_hash[param.intern] || :absent
   end
 
+  # Creates a new provider that is optionally initialized from a resource or a hash of properties.
+  # If no argument is specified, a new non specific provider is initialized. If a resource is given
+  # it is remembered for further operations. If a hash is used it becomes the internal `@property_hash`
+  # structure of the provider - this hash holds the current state property values of system entities
+  # as they are being discovered by querying or other operations (typically getters).
+  # 
+  # @todo The use of a hash as a parameter needs a better exaplanation; why is this done? What is the intent? 
+  # @param resource [Puppet::Resource, Hash] optional resource or hash
+  #
   def initialize(resource = nil)
     if resource.is_a?(Hash)
       # We don't use a duplicate here, because some providers (ParsedFile, at least)
@@ -362,6 +551,10 @@ class Puppet::Provider
     end
   end
 
+  # Returns the name of the resource this provider is operating on.
+  # @return [String] the name of the resource instance (e.g. the file path of a File).
+  # @raise [Puppet::DevError] if no resource is set, or no name defined.
+  #
   def name
     if n = @property_hash[:name]
       return n
@@ -372,24 +565,53 @@ class Puppet::Provider
     end
   end
 
-  # Set passed params as the current values.
+  # Sets the given parameters values as the current values for those parameters.
+  # Other parameters are unchanged.
+  # @param [Array<Puppet::Parameter] the parameters with values that should be set
+  # @return [void]
+  #
   def set(params)
     params.each do |param, value|
       @property_hash[param.intern] = value
     end
   end
 
+  # @return [String] Returns a human readable string with information about the resource and the provider.
   def to_s
     "#{@resource}(provider=#{self.class.name})"
   end
 
-  # Make providers comparable.
+  # Makes providers comparable.
   include Comparable
+  # Compares this provider against another provider.
+  # Comparison is only possible with another provider (no other class).
+  # The ordering is based on the class name of the two providers.
+  #
+  # @return [-1,0,+1, nil] A comparison result -1, 0, +1 if this is before other, equal or after other. Returns
+  #   nil oif not comparable to other.
+  # @see Comparable
   def <=>(other)
     # We can only have ordering against other providers.
     return nil unless other.is_a? Puppet::Provider
     # Otherwise, order by the providers class name.
     return self.class.name <=> other.class.name
   end
+  
+  # @comment Document prefetch here as it does not exist anywhere else (called from transaction if implemented)
+  # @!method self.prefetch(resource_hash)
+  # @abstract A subclass may implement this - it is not implemented in the Provider class
+  # This method may be implemented by a provider in order to pre-fetch resource properties.
+  # If implemented it should set the provider instance of the managed resources to a provider with the
+  # fetched state (i.e. what is returned from the {instances} method).
+  # @param resources_hash [Hash<{String => Puppet::Resource}>] map from name to resource of resources to prefetch
+  # @return [void]
+  
+  # @comment Document flush here as it does not exist anywhere (called from transaction if implemented)
+  # @!method flush()
+  # @abstract A subclass may implement this - it is not implemented in the Provider class
+  # This method may be implemented by a provider in order to flush properties that has not been individually
+  # applied to the managed entity's current state.
+  # @return [void]
+
 end