Merge branch 'v2.1.x' into v2.2.x

* v2.1.x:
  (maint) Add semantic versioning info to README
  Docs: Clarify the use case for the anchor type
  Docs: Remove author emails from stdlib functions
  Docs: Copyedit function doc strings
  Docs: Correct indentation of markdown code examples
  Docs: Update documentation of stdlib classes
  Docs: Update file_line documentation
  Docs: Improve example in merge function

2 files changed, 37 insertions, 17 deletions

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