From ad7a42c26d8ec8f4f1a8ec30c1311a4e47ef57fd Mon Sep 17 00:00:00 2001
From: Peter Souter <petems@users.noreply.github.com>
Date: Fri, 19 May 2017 08:58:00 +0100
Subject: [PATCH] Updates docs for puppet functions (#208)

* redisget() doc update
* getvar_emptystring() doc update
---
 .../parser/functions/getvar_emptystring.rb    | 34 +++++++++++--------
 lib/puppet/parser/functions/redisget.rb       | 16 ++++++---
 2 files changed, 30 insertions(+), 20 deletions(-)

diff --git a/lib/puppet/parser/functions/getvar_emptystring.rb b/lib/puppet/parser/functions/getvar_emptystring.rb
index 8d23c68a..67ab7945 100644
--- a/lib/puppet/parser/functions/getvar_emptystring.rb
+++ b/lib/puppet/parser/functions/getvar_emptystring.rb
@@ -1,20 +1,24 @@
 module Puppet::Parser::Functions
 
-  newfunction(:getvar_emptystring, :type => :rvalue, :doc => <<-'ENDHEREDOC') do |args|
-    Lookup a variable in a remote namespace.
-    Return an empty string rather than undef/nil if it could not be found
-
-    For example:
-
-        $foo = getvar('site::data::foo')
-        # Equivalent to $foo = $site::data::foo
-
-    This is useful if the namespace itself is stored in a string:
-
-        $datalocation = 'site::data'
-        $bar = getvar("${datalocation}::bar")
-        # Equivalent to $bar = $site::data::bar
-    ENDHEREDOC
+  newfunction(:getvar_emptystring, :type => :rvalue, :doc => <<-DOC
+Return a variable in a remote namespace, but returns an empty
+string if the variable is undefined or can't be found.
+This is useful when trying to lookup a value that might be undefined
+on first run, like a fact for an application that will be installed as
+part of a Puppet run, but you don't want the reference to an undefined variable
+to cause an error when strict variables are enabled.
+@param variable [String] The variable to lookup
+@return [String] The value of the variable if found
+@return [String] An empty string if the variable is not found eg. `''`
+@example Checking a variable exists (Equivalent to $foo = $site::data::foo)
+  $foo = getvar('site::data::foo')
+@example Calling the function. (Equivalent to $bar = $site::data::bar)
+  $datalocation = 'site::data'
+  $bar = getvar("${datalocation}::bar")
+@example Combining with the pick() function
+  $redis_version_real = pick(getvar_emptystring('redis_server_version'), '3.2.1')
+DOC
+  ) do |args|
 
     unless args.length == 1
       raise Puppet::ParseError, ("getvar_emptystring(): wrong number of arguments (#{args.length}; must be 1)")
diff --git a/lib/puppet/parser/functions/redisget.rb b/lib/puppet/parser/functions/redisget.rb
index 7134267e..579aba19 100644
--- a/lib/puppet/parser/functions/redisget.rb
+++ b/lib/puppet/parser/functions/redisget.rb
@@ -1,11 +1,17 @@
 require 'redis'
 
 module Puppet::Parser::Functions
-  newfunction(:redisget, :type => :rvalue, :doc => <<-EOS
-    Returns the value of the key being looked up or nil if the key does not
-    exist. Takes two arguments, the first being a string value of the key to be
-    looked up and the second is the URL to the Redis service.
-    EOS
+  newfunction(:redisget, :type => :rvalue, :doc => <<-DOC
+Returns the value of the key being looked up or nil if the key does not
+exist. Takes two arguments, the first being a string value of the key to be
+looked up and the second is the URL to the Redis service.
+@param redis_key [String] The key to look up in redis.
+@param redis_uri [String] The endpoint of the Redis instance.
+@return [String] The value of the key from redis
+@return [String] An empty string eg. `''`
+@example Calling the function.
+  $version = redisget('version.myapp', 'redis://redis.example.com:6379')
+DOC
   ) do |args|
 
     raise(Puppet::ParseError, "redisget(): Wrong number of arguments given (#{args.size} for 2)") if args.size != 2