fqdn_rotate: Improve documentation

Author: elyscape

README.markdown

@@ -259,7 +259,20 @@ fqdn_rand_string(10, '', 'custom seed')
 
 #### `fqdn_rotate`
 
-Rotates an array a random number of times, based on a node's fqdn. *Type*: rvalue.
+Rotates an array or string a random number of times, combining the `$fqdn` fact and an optional seed for repeatable randomness.
+
+*Usage:*
+~~~
+fqdn_rotate(VALUE, [SEED])
+~~~
+*Examples:*
+~~~
+fqdn_rotate(['a', 'b', 'c', 'd'])
+fqdn_rotate('abcd')
+fqdn_rotate([1, 2, 3], 'custom seed')
+~~~
+
+*Type*: rvalue.
 
 #### `get_module_path`
 

lib/puppet/parser/functions/fqdn_rotate.rb

@@ -2,16 +2,23 @@
 # fqdn_rotate.rb
 #
 
-module Puppet::Parser::Functions
-  newfunction(:fqdn_rotate, :type => :rvalue, :doc => <<-EOS
-Rotates an array a random number of times based on a nodes fqdn.
-    EOS
-  ) do |arguments|
+Puppet::Parser::Functions.newfunction(
+  :fqdn_rotate,
+  :type => :rvalue,
+  :doc => "Usage: `fqdn_rotate(VALUE, [SEED])`. VALUE is required and
+  must be an array or a string. SEED is optional and may be any number
+  or string.
+
+  Rotates VALUE a random number of times, combining the `$fqdn` fact and
+  the value of SEED for repeatable randomness. (That is, each node will
+  get a different random rotation from this function, but a given node's
+  result will be the same every time unless its hostname changes.) Adding
+  a SEED can be useful if you need more than one unrelated rotation.") do |args|
 
     raise(Puppet::ParseError, "fqdn_rotate(): Wrong number of arguments " +
-      "given (#{arguments.size} for 1)") if arguments.size < 1
+      "given (#{args.size} for 1)") if args.size < 1
 
-    value = arguments.shift
+    value = args.shift
     require 'digest/md5'
 
     unless value.is_a?(Array) || value.is_a?(String)
@@ -31,7 +38,7 @@ module Puppet::Parser::Functions
 
     elements = result.size
 
-    seed = Digest::MD5.hexdigest([lookupvar('::fqdn'),arguments].join(':')).hex
+    seed = Digest::MD5.hexdigest([lookupvar('::fqdn'),args].join(':')).hex
     # deterministic_rand() was added in Puppet 3.2.0; reimplement if necessary
     if Puppet::Util.respond_to?(:deterministic_rand)
       offset = Puppet::Util.deterministic_rand(seed, elements).to_i
@@ -51,7 +58,6 @@ module Puppet::Parser::Functions
     result = string ? result.join : result
 
     return result
-  end
 end
 
 # vim: set ts=2 sw=2 et :