Merge pull request #16 from nfagerlund/docs/v2.0.0/XXXX_function_doc_updates

Docs/v2.0.0/xxxx function doc updates

13 files changed, 99 insertions, 84 deletions

diff --git a/lib/puppet/parser/functions/getvar.rb b/lib/puppet/parser/functions/getvar.rb
index ffd774d..1621149 100644
--- a/lib/puppet/parser/functions/getvar.rb
+++ b/lib/puppet/parser/functions/getvar.rb
@@ -5,11 +5,14 @@ module Puppet::Parser::Functions
 
     For example:
 
-      $foo = getvar('site::data::foo')
+        $foo = getvar('site::data::foo')
+        # Equivalent to $foo = $site::data::foo
 
     This is useful if the namespace itself is stored in a string:
 
-      $bar = getvar("${datalocation}::bar")
+        $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/has_key.rb b/lib/puppet/parser/functions/has_key.rb
index 9c1c4c3..4657cc2 100644
--- a/lib/puppet/parser/functions/has_key.rb
+++ b/lib/puppet/parser/functions/has_key.rb
@@ -1,16 +1,17 @@
 module Puppet::Parser::Functions
 
   newfunction(:has_key, :type => :rvalue, :doc => <<-'ENDHEREDOC') do |args|
-    determine if a hash has a certain key value.
+    Determine if a hash has a certain key value.
 
     Example:
-      $my_hash = {'key_one' => 'value_one'}
-      if has_key($my_hash, 'key_two') {
-        notice('we will not reach here')
-      }
-      if has_key($my_hash, 'key_one') {
-        notice('this will be printed')
-      }
+
+        $my_hash = {'key_one' => 'value_one'}
+        if has_key($my_hash, 'key_two') {
+          notice('we will not reach here')
+        }
+        if has_key($my_hash, 'key_one') {
+          notice('this will be printed')
+        }
 
     ENDHEREDOC
 
diff --git a/lib/puppet/parser/functions/loadyaml.rb b/lib/puppet/parser/functions/loadyaml.rb
index 0f16f69..10c4005 100644
--- a/lib/puppet/parser/functions/loadyaml.rb
+++ b/lib/puppet/parser/functions/loadyaml.rb
@@ -1,12 +1,12 @@
 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:
 
-      $myhash = loadyaml('/etc/puppet/data/myhash.yaml')
+        $myhash = loadyaml('/etc/puppet/data/myhash.yaml')
     ENDHEREDOC
 
     unless args.length == 1
diff --git a/lib/puppet/parser/functions/merge.rb b/lib/puppet/parser/functions/merge.rb
index d2dc0f9..6ec085e 100644
--- a/lib/puppet/parser/functions/merge.rb
+++ b/lib/puppet/parser/functions/merge.rb
@@ -4,10 +4,13 @@ module Puppet::Parser::Functions
 
     For example:
 
-      $hash1 = {'one' => 1, 'two', => 2}
-      $hash1 = {'two' => 2, 'three', => 2}
-      $merged_hash = merge($hash1, $hash2)
-      # merged_hash =  {'one' => 1, 'two' => 2, 'three' => 2}
+        $hash1 = {'one' => 1, 'two', => 2}
+        $hash2 = {'two' => 'dos', 'three', => 'tres'}
+        $merged_hash = merge($hash1, $hash2)
+        # The resulting hash is equivalent to:
+        # $merged_hash =  {'one' => 1, 'two' => 'dos', 'three' => 'tres'}
+
+    When there is a duplicate key, the key in the rightmost hash will "win."
 
     ENDHEREDOC
 
diff --git a/lib/puppet/parser/functions/validate_array.rb b/lib/puppet/parser/functions/validate_array.rb
index a7a7165..34b5118 100644
--- 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 49e6378..62c1d88 100644
--- a/lib/puppet/parser/functions/validate_bool.rb
+++ b/lib/puppet/parser/functions/validate_bool.rb
@@ -1,27 +1,22 @@
 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")
         validate_bool("true")
         validate_bool($some_array)
 
-    * Jeff McCune <jeff@puppetlabs.com>
-    * Dan Bode <dan@puppetlabs.com>
-
     ENDHEREDOC
 
     unless args.length > 0 then
diff --git a/lib/puppet/parser/functions/validate_hash.rb b/lib/puppet/parser/functions/validate_hash.rb
index 1443318..9bdd543 100644
--- a/lib/puppet/parser/functions/validate_hash.rb
+++ b/lib/puppet/parser/functions/validate_hash.rb
@@ -1,25 +1,21 @@
 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')
         $undefined = undef
         validate_hash($undefined)
 
-    * Jeff McCune <jeff@puppetlabs.com>
-
     ENDHEREDOC
 
     unless args.length > 0 then
diff --git a/lib/puppet/parser/functions/validate_re.rb b/lib/puppet/parser/functions/validate_re.rb
index 583f26a..8033ca3 100644
--- a/lib/puppet/parser/functions/validate_re.rb
+++ b/lib/puppet/parser/functions/validate_re.rb
@@ -1,24 +1,22 @@
 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' ])
 
-    Jeff McCune <jeff@puppetlabs.com>
-
     ENDHEREDOC
     if args.length != 2 then
       raise Puppet::ParseError, ("validate_re(): wrong number of arguments (#{args.length}; must be 2)")
diff --git a/lib/puppet/parser/functions/validate_string.rb b/lib/puppet/parser/functions/validate_string.rb
index d0e1376..e667794 100644
--- 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' ])
diff --git a/lib/puppet/type/anchor.rb b/lib/puppet/type/anchor.rb
index 0c28b1c..6b81732 100644
--- a/lib/puppet/type/anchor.rb
+++ b/lib/puppet/type/anchor.rb
@@ -2,23 +2,32 @@ Puppet::Type.newtype(:anchor) do
   desc <<-'ENDOFDESC'
   A simple resource type intended to be used as an anchor in a composite class.
 
+  In Puppet 2.6, when a class declares another class, the resources in the
+  interior class are not contained by the exterior class. This interacts badly
+  with the pattern of composing complex modules from smaller classes, as it
+  makes it impossible for end users to specify order relationships between the
+  exterior class and other modules.
+
+  The anchor type lets you work around this. By sandwiching any interior
+  classes between two no-op resources that _are_ contained by the exterior
+  class, you can ensure that all resources in the module are contained.
+
       class ntp {
+        # These classes will have the correct order relationship with each
+        # other. However, without anchors, they won't have any order
+        # relationship to Class['ntp'].
         class { 'ntp::package': }
         -> class { 'ntp::config': }
         -> class { 'ntp::service': }
 
-        # These two resources "anchor" the composed classes
-        # such that the end user may use "require" and "before"
-        # relationships with Class['ntp']
-        anchor { 'ntp::begin': }   -> class  { 'ntp::package': }
-        class  { 'ntp::service': } -> anchor { 'ntp::end': }
+        # These two resources "anchor" the composed classes within the ntp
+        # class.
+        anchor { 'ntp::begin': } -> Class['ntp::package']
+        Class['ntp::service']    -> anchor { 'ntp::end': }
       }
 
-  This resource allows all of the classes in the ntp module to be contained
-  within the ntp class from a dependency management point of view.
-
   This allows the end user of the ntp module to establish require and before
-  relationships easily:
+  relationships with Class['ntp']:
 
       class { 'ntp': } -> class { 'mcollective': }
       class { 'mcollective': } -> class { 'ntp': }
diff --git a/lib/puppet/type/file_line.rb b/lib/puppet/type/file_line.rb
index aacd6d9..8b45897 100644
--- a/lib/puppet/type/file_line.rb
+++ b/lib/puppet/type/file_line.rb
@@ -1,14 +1,25 @@
 Puppet::Type.newtype(:file_line) do
 
   desc <<-EOT
-  Type that can append whole a line to a file if it does not already contain it.
-
-  Example:
-
-  file_line { 'sudo_rule':
-    path => '/etc/sudoers',
-    line => '%admin ALL=(ALL) ALL',
-  }
+    Ensures that a given line is contained within a file.  The implementation
+    matches the full line, including whitespace at the beginning and end.  If
+    the line is not contained in the given file, Puppet will add the line to
+    ensure the desired state.  Multiple resources may be declared to manage
+    multiple lines in the same file.
+
+    Example:
+
+        file_line { 'sudo_rule':
+          path => '/etc/sudoers',
+          line => '%sudo ALL=(ALL) ALL',
+        }
+        file_line { 'sudo_rule_nopw':
+          path => '/etc/sudoers',
+          line => '%sudonopw ALL=(ALL) NOPASSWD: ALL',
+        }
+
+    In this example, Puppet will ensure both of the specified lines are
+    contained in the file /etc/sudoers.
 
   EOT
 
diff --git a/manifests/init.pp b/manifests/init.pp
index c804568..500ad77 100644
--- a/manifests/init.pp
+++ b/manifests/init.pp
@@ -1,16 +1,18 @@
 # Class: stdlib
 #
-# This module manages stdlib
+# This module manages stdlib. Most of stdlib's features are automatically
+# loaded by Puppet, but this class should be declared in order to use the
+# standardized run stages.
 #
-# Parameters:
+# Parameters: none
 #
 # Actions:
 #
-# Requires:
+#   Declares all other classes in the stdlib module. Currently, this consists
+#   of stdlib::stages.
 #
-# Sample Usage:
+# Requires: nothing
 #
-# [Remember: No empty lines between comments and class definition]
 class stdlib {
 
   class { 'stdlib::stages': }
diff --git a/manifests/stages.pp b/manifests/stages.pp
index 365b905..eb15fd6 100644
--- a/manifests/stages.pp
+++ b/manifests/stages.pp
@@ -1,8 +1,9 @@
 # Class: stdlib::stages
 #
-# This class manages a standard set of Run Stages for Puppet.
+# This class manages a standard set of run stages for Puppet. It is managed by
+# the stdlib class, and should not be declared independently.
 #
-# The high level stages are (In order):
+# The high level stages are (in order):
 #
 #  * setup
 #  * main
@@ -13,19 +14,19 @@
 #  * deploy_app
 #  * deploy
 #
-# Parameters:
+# Parameters: none
 #
 # Actions:
 #
 #   Declares various run-stages for deploying infrastructure,
 #   language runtimes, and application layers.
 #
-# Requires:
+# Requires: nothing
 #
 # Sample Usage:
 #
 #  node default {
-#    include stdlib::stages
+#    include stdlib
 #    class { java: stage => 'runtime' }
 #  }
 #