Docs: Copyedit function doc strings

This commit makes several minor consistency and wording edits to the doc
strings of the stdlib functions.

diff --git a/lib/puppet/parser/functions/getvar.rb b/lib/puppet/parser/functions/getvar.rb
index 3ca179f7027582bbd0125f0ec5c71173834586e7..162114995b3f6645b7ec884d434d86e260f9828c 100644 (file)
--- a/lib/puppet/parser/functions/getvar.rb
+++ b/lib/puppet/parser/functions/getvar.rb
@@ -6,10 +6,13 @@ module Puppet::Parser::Functions
     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
 
     unless args.length == 1

diff --git a/lib/puppet/parser/functions/loadyaml.rb b/lib/puppet/parser/functions/loadyaml.rb
index 4ccc95b8cf19dc253272a74083d90dae20c91b5b..10c400501be487cf14221fdab40ee17ddb681307 100644 (file)
--- a/lib/puppet/parser/functions/loadyaml.rb
+++ b/lib/puppet/parser/functions/loadyaml.rb
@@ -1,8 +1,8 @@
 module Puppet::Parser::Functions
 
   newfunction(:loadyaml, :type => :rvalue, :doc => <<-'ENDHEREDOC') do |args|
-    Load a YAML file and return the data if it contains an Array, String, or Hash
-    as a Puppet variable.
+    Load a YAML file containing an array, string, or hash, and return the data
+    in the corresponding native data type.
 
     For example:
 

diff --git a/lib/puppet/parser/functions/validate_array.rb b/lib/puppet/parser/functions/validate_array.rb
index a7a7165bdc3e7f7d29b57c11bd029cbe077368f4..34b511825cc2f9666ed8f2985ada820febce695a 100644 (file)
--- a/lib/puppet/parser/functions/validate_array.rb
+++ b/lib/puppet/parser/functions/validate_array.rb
@@ -1,17 +1,15 @@
 module Puppet::Parser::Functions
 
   newfunction(:validate_array, :doc => <<-'ENDHEREDOC') do |args|
-    Validate all passed values are a Array data structure
-    value does not pass the check.
+    Validate that all passed values are array data structures. Abort catalog
+    compilation if any value fails this check.
 
-    Example:
-
-    These values validate
+    The following values will pass:
 
         $my_array = [ 'one', 'two' ]
         validate_array($my_array)
 
-    These values do NOT validate
+    The following values will fail, causing compilation to abort:
 
         validate_array(true)
         validate_array('some_string')

diff --git a/lib/puppet/parser/functions/validate_bool.rb b/lib/puppet/parser/functions/validate_bool.rb
index 49e6378e4b88b64dd4f0f804571164da03d5e3d1..82a45fb13056448506aecdfe32e0e07762b4f5fa 100644 (file)
--- a/lib/puppet/parser/functions/validate_bool.rb
+++ b/lib/puppet/parser/functions/validate_bool.rb
@@ -1,18 +1,16 @@
 module Puppet::Parser::Functions
 
   newfunction(:validate_bool, :doc => <<-'ENDHEREDOC') do |args|
-    Validate all passed values are true or false.  Abort catalog compilation if the
-    value does not pass the check.
+    Validate that all passed values are either true or false. Abort catalog
+    compilation if any value fails this check.
 
-    Example:
-
-    These booleans validate
+    The following values will pass:
 
         $iamtrue = true
         validate_bool(true)
         validate_bool(true, true, false, $iamtrue)
 
-    These strings do NOT validate and will abort catalog compilation
+    The following values will fail, causing compilation to abort:
 
         $some_array = [ true ]
         validate_bool("false")

diff --git a/lib/puppet/parser/functions/validate_hash.rb b/lib/puppet/parser/functions/validate_hash.rb
index 144331841549db9679d2c0036ba7b155f9f8c9fe..1b1c854fbe653baf1e41c2f18b9fd923ec21f54f 100644 (file)
--- a/lib/puppet/parser/functions/validate_hash.rb
+++ b/lib/puppet/parser/functions/validate_hash.rb
@@ -1,17 +1,15 @@
 module Puppet::Parser::Functions
 
   newfunction(:validate_hash, :doc => <<-'ENDHEREDOC') do |args|
-    Validate all passed values are a Hash data structure
-    value does not pass the check.
+    Validate that all passed values are hash data structures. Abort catalog
+    compilation if any value fails this check.
 
-    Example:
-
-    These values validate
+    The following values will pass:
 
         $my_hash = { 'one' => 'two' }
         validate_hash($my_hash)
 
-    These values do NOT validate
+    The following values will fail, causing compilation to abort:
 
         validate_hash(true)
         validate_hash('some_string')

diff --git a/lib/puppet/parser/functions/validate_re.rb b/lib/puppet/parser/functions/validate_re.rb
index 583f26ab2efc01cc0a4fe20c6d47492a4a1f2eeb..9e61ef596b373e4467d938bfb9d832429c403907 100644 (file)
--- a/lib/puppet/parser/functions/validate_re.rb
+++ b/lib/puppet/parser/functions/validate_re.rb
@@ -1,19 +1,19 @@
 module Puppet::Parser::Functions
 
   newfunction(:validate_re, :doc => <<-'ENDHEREDOC') do |args|
-    Perform simple validation of a string against a regular expression.  The second
-    argument of the function should be a string regular expression (without the //'s)
-    or an array of regular expressions.  If none of the regular expressions in the array
-    match the string passed in, then an exception will be raised.
+    Perform simple validation of a string against one or more regular
+    expressions. The first argument of this function should be a string to
+    test, and the second argument should be a stringified regular expression
+    (without the // delimiters) or an array of regular expressions.  If none
+    of the regular expressions match the string passed in, compilation will
+    abort with a parse error.
 
-    Example:
-
-    These strings validate against the regular expressions
+    The following strings will validate against the regular expressions:
 
         validate_re('one', '^one$')
         validate_re('one', [ '^one', '^two' ])
 
-    These strings do NOT validate
+    The following strings will fail to validate, causing compilation to abort:
 
         validate_re('one', [ '^two', '^three' ])
 

diff --git a/lib/puppet/parser/functions/validate_string.rb b/lib/puppet/parser/functions/validate_string.rb
index d0e137683a911c7c6f26d46dd80f94a41581f232..e667794a6791c3b5c094bccd0de65c0d5106c74c 100644 (file)
--- a/lib/puppet/parser/functions/validate_string.rb
+++ b/lib/puppet/parser/functions/validate_string.rb
@@ -1,17 +1,15 @@
 module Puppet::Parser::Functions
 
   newfunction(:validate_string, :doc => <<-'ENDHEREDOC') do |args|
-    Validate all passed values are a string data structure
-    value does not pass the check.
+    Validate that all passed values are string data structures. Abort catalog
+    compilation if any value fails this check.
 
-    Example:
-
-    These values validate
+    The following values will pass:
 
         $my_string = "one two"
-        validate_string($my_string)
+        validate_string($my_string, 'three')
 
-    These values do NOT validate
+    The following values will fail, causing compilation to abort:
 
         validate_string(true)
         validate_string([ 'some', 'array' ])