Merge pull request #430 from mhaskel/gjngeldenhuis-docupdate

Clarifying behaviour of attributes and adding an extra example.

lib/puppet/type/file_line.rb

@@ -3,16 +3,17 @@
   desc <<-EOT
     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.
+    the line is not contained in the given file, Puppet will append the line to
+    the end of the file 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',
@@ -21,6 +22,18 @@
     In this example, Puppet will ensure both of the specified lines are
     contained in the file /etc/sudoers.
 
+    Match Example:
+
+        file_line { 'bashrc_proxy':
+          ensure => present,
+          path   => '/etc/bashrc',
+          line   => 'export HTTP_PROXY=http://squid.puppetlabs.vm:3128',
+          match  => '^export\ HTTP_PROXY\=',
+        }
+
+    In this code example match will look for a line beginning with export 
+    followed by HTTP_PROXY and replace it with the value in line.
+
     **Autorequires:** If Puppet is managing the file that will contain the line
     being managed, the file_line resource will autorequire that file.
 
@@ -36,12 +49,15 @@
   end
 
   newparam(:match) do
-    desc 'An optional regular expression to run against existing lines in the file;\n' +
-        'if a match is found, we replace that line rather than adding a new line.'
+    desc 'An optional ruby regular expression to run against existing lines in the file.' + 
+         ' If a match is found, we replace that line rather than adding a new line.' +
+         ' A regex comparisson is performed against the line value and if it does not' +
+         ' match an exception will be raised. '
   end
 
   newparam(:multiple) do
-    desc 'An optional value to determine if match can change multiple lines.'
+    desc 'An optional value to determine if match can change multiple lines.' +
+         ' If set to false, an exception will be raised if more than one line matches'
     newvalues(true, false)
   end
 
@@ -50,7 +66,7 @@
   end
 
   newparam(:line) do
-    desc 'The line to be appended to the file located by the path parameter.'
+    desc 'The line to be appended to the file or used to replace matches found by the match attribute.'
   end
 
   newparam(:path) do