[Pkg-puppet-devel] [facter] 194/352: (doc) Update the Resolution#confine API docs

[Stig Sandbeck Mathisen]

This is an automated email from the git hooks/post-receive script.

ssm pushed a commit to branch master
in repository facter.

commit 21f10c05398bc3699f64f5c732c18f48dfc1010d
Author: Jeff McCune <jeff at puppetlabs.com>
Date:   Wed Apr 3 13:40:37 2013 -0700

    (doc) Update the Resolution#confine API docs
    
    Without this patch, the API documentation for the
    Facter::Util::Resolution#confine is a bit muddled and confusing.  This
    confusion is caused by the different, overloaded, forms of arguments
    that #confine accepts.
    
    This patch addresses the problem by using the @overload YARD tag to
    separate out each form, document the arguments for each form, and
    provide a clear example for each form.
    
    Back ported onto facter-2 by Adrien thebo <adrien at puppetlabs.com>
    
    Conflicts:
    	lib/facter/util/resolution.rb
---
 lib/facter/core/suitable.rb | 61 ++++++++++++++++++++++++++++++++-------------
 1 file changed, 43 insertions(+), 18 deletions(-)

diff --git a/lib/facter/core/suitable.rb b/lib/facter/core/suitable.rb
index e34b5e8..1b3c04f 100644
--- a/lib/facter/core/suitable.rb
+++ b/lib/facter/core/suitable.rb
@@ -23,29 +23,54 @@ module Facter::Core::Suitable
     @weight = weight
   end
 
-  # Sets the conditions for this resolution to be used. This takes a
-  # hash of fact names and values. Every fact must match the values
-  # given for that fact, otherwise this resolution will not be
-  # considered suitable. The values given for a fact can be an array, in
-  # which case the value of the fact must be in the array for it to
-  # match.
+  # Sets the conditions for this resolution to be used.  This method accepts
+  # multiple forms of arguments to determine suitability.
   #
-  # @param confines [Hash{String => Object}] a hash of facts and the
-  #   values they should have in order for this resolution to be
-  #   used
+  # @return [void]
+  #
+  # @api public
   #
-  # @example Confining to Linux
-  #     Facter.add(:powerstates) do
-  #       # This resolution only makes sense on linux systems
-  #       confine :kernel => "Linux"
-  #       setcode do
-  #         Facter::Util::Resolution.exec('cat /sys/power/states')
+  # @overload confine(confines)
+  #   Confine a fact to a specific fact value or values.  This form takes a
+  #   hash of fact names and values. Every fact must match the values given for
+  #   that fact, otherwise this resolution will not be considered suitable. The
+  #   values given for a fact can be an array, in which case the value of the
+  #   fact must be in the array for it to match.
+  #   @param [Hash{String,Symbol=>String,Array<String>}] confines set of facts identified by the hash keys whose
+  #     fact value must match the argument value.
+  #   @example Confining to Linux
+  #       Facter.add(:powerstates) do
+  #         # This resolution only makes sense on linux systems
+  #         confine :kernel => "Linux"
+  #         setcode do
+  #           File.read('/sys/power/states')
+  #         end
   #       end
-  #     end
   #
-  # @return [void]
+  # @overload confine(confines, &block)
+  #   Confine a fact to a block with the value of a specified fact yielded to
+  #   the block.
+  #   @param [String,Symbol] confines the fact name whose value should be
+  #     yielded to the block
+  #   @param [Proc] block determines the suitability of the fact.  If the block
+  #     evaluates to `false` or `nil` then the confined fact will not be
+  #     evaluated.
+  #   @yield [value] the value of the fact identified by {confines}
+  #   @example Confine the fact to a host with an ipaddress in a specific
+  #     subnet
+  #       confine :ipaddress do |addr|
+  #         require 'ipaddr'
+  #         IPAddr.new('192.168.0.0/16').include? addr
+  #       end
   #
-  # @api public
+  # @overload confine(&block)
+  #   Confine a fact to a block.  The fact will be evaluated only if the block
+  #   evaluates to something other than `false` or `nil`.
+  #   @param [Proc] block determines the suitability of the fact.  If the block
+  #     evaluates to `false` or `nil` then the confined fact will not be
+  #     evaluated.
+  #   @example Confine the fact to systems with a specific file.
+  #       confine { File.exist? '/bin/foo' }
   def confine(confines = nil, &block)
     case confines
     when Hash

-- 
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-puppet/facter.git