Merge pull request #2013 from nfagerlund/fqdn_rand_redux

Docs: Explain the usage of fqdn_rand more effectively

Author: kylo

lib/puppet/parser/functions/fqdn_rand.rb

@@ -1,15 +1,20 @@
 require 'digest/md5'
 
 Puppet::Parser::Functions::newfunction(:fqdn_rand, :arity => -2, :type => :rvalue, :doc =>
-  "Generates random numbers based on the node's fqdn. Generated random values
-  will be a range from 0 up to and excluding n, where n is the first parameter.
-  The second argument specifies a number or string to add to the seed and is optional.
+  "Usage: `fqdn_rand(MAX, [SEED])`. MAX is required and must be a positive
+  integer; SEED is optional and may be any number or string.
 
-  Examples:
+  Generates a random whole number greater than or equal to 0 and less than MAX,
+  combining the `$fqdn` fact and the value of SEED for repeatable randomness.
+  (That is, each node will get a different random number from this function, but
+  a given node's result will be the same every time unless its hostname changes.)
 
-      $random_number = fqdn_rand(30)
-      $random_number_seeded = fqdn_rand(30,30)
-      $random_number_seeded2 = fqdn_rand(30,'foo')") do |args|
+  This function is usually used for spacing out runs of resource-intensive cron
+  tasks that run on many nodes, which could cause a thundering herd or degrade
+  other services if they all fire at once. Adding a SEED can be useful when you
+  have more than one such task and need several unrelated random numbers per
+  node. (For example, `fqdn_rand(30)`, `fqdn_rand(30, 'expensive job 1')`, and
+  `fqdn_rand(30, 'expensive job 2')` will produce totally different numbers.)") do |args|
     max = args.shift.to_i
     seed = Digest::MD5.hexdigest([self['::fqdn'],args].join(':')).hex
     Puppet::Util.deterministic_rand(seed,max)