[Pkg-puppet-devel] [facter] 194/352: (doc) Update the Resolution#confine API docs
Stig Sandbeck Mathisen
ssm at debian.org
Sun Apr 6 22:21:45 UTC 2014
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
More information about the Pkg-puppet-devel
mailing list