Merge pull request #24 from nfagerlund/maint/2.7.x/misc_doc_fixes

    Merge branch 'maint/2.7.x/misc_doc_fixes' into 2.7.x
    
    * maint/2.7.x/misc_doc_fixes:
      (#7853) Clarify and complete docs for the tagmail report processor
      Maint: Mention that audit metaparameter will accept "all"
      Maint: Adjust wording for file type's content parameter
      Maint: Fix poor documentation for versioncmp function.

4 files changed, 32 insertions, 21 deletions

diff --git a/lib/puppet/parser/functions/versioncmp.rb b/lib/puppet/parser/functions/versioncmp.rb
index 6091e0923..a06866876 100644
--- a/lib/puppet/parser/functions/versioncmp.rb
+++ b/lib/puppet/parser/functions/versioncmp.rb
@@ -4,19 +4,19 @@ require 'puppet/util/package'
       Puppet::Parser::Functions::newfunction(
         :versioncmp, :type => :rvalue,
 
-  :doc => "Compares two versions
+  :doc => "Compares two version numbers.
 
 Prototype:
 
     \$result = versioncmp(a, b)
 
-Where a and b are arbitrary version strings
+Where a and b are arbitrary version strings.
 
-This functions returns a number:
+This function returns:
 
-* Greater than 0 if version a is greater than version b
-* Equal to 0 if both version are equals
-* Less than 0 if version a is less than version b
+* `1` if version a is greater than version b
+* `0` if the versions are equal
+* `-1` if version a is less than version b
 
 Example:
 
@@ -24,6 +24,9 @@ Example:
         notice('2.6-1 is > than 2.4.5')
     }
 
+This function uses the same version comparison algorithm used by Puppet's
+`package` type.
+
 ") do |args|
 
   unless args.length == 2
diff --git a/lib/puppet/reports/tagmail.rb b/lib/puppet/reports/tagmail.rb
index e17143e2f..c37341e11 100644
--- a/lib/puppet/reports/tagmail.rb
+++ b/lib/puppet/reports/tagmail.rb
@@ -8,21 +8,24 @@ Puppet::Reports.register_report(:tagmail) do
   desc "This report sends specific log messages to specific email addresses
     based on the tags in the log messages.  
 
-    See the [UsingTags tag documentation](http://projects.puppetlabs.com/projects/puppet/wiki/Using_Tags) for more information on tags.
+    See the [documentation on tags](http://projects.puppetlabs.com/projects/puppet/wiki/Using_Tags) for more information.
 
-    To use this report, you must create a `tagmail.conf` (in the location
-    specified by `tagmap`).  This is a simple file that maps tags to
+    To use this report, you must create a `tagmail.conf` file in the location
+    specified by the `tagmap` setting.  This is a simple file that maps tags to
     email addresses:  Any log messages in the report that match the specified
     tags will be sent to the specified email addresses.
 
-    Tags must be comma-separated, and they can be negated so that messages
-    only match when they do not have that tag.  The tags are separated from
-    the email addresses by a colon, and the email addresses should also
-    be comma-separated.
+    Lines in the `tagmail.conf` file consist of a comma-separated list
+    of tags, a colon, and a comma-separated list of email addresses.
+    Tags can be !negated with a leading exclamation mark, which will
+    subtract any messages with that tag from the set of events handled
+    by that line.
 
-    Lastly, there is an `all` tag that will always match all log messages.
+    Puppet's log levels (`debug`, `info`, `notice`, `warning`, `err`,
+    `alert`, `emerg`, `crit`, and `verbose`) can also be used as tags,
+    and there is an `all` tag that will always match all log messages.
 
-    Here is an example `tagmail.conf`:
+    An example `tagmail.conf`:
 
         all: me@domain.com
         webserver, !mailserver: httpadmins@domain.com
@@ -30,8 +33,9 @@ Puppet::Reports.register_report(:tagmail) do
     This will send all messages to `me@domain.com`, and all messages from
     webservers that are not also from mailservers to `httpadmins@domain.com`.
 
-    If you are using anti-spam controls, such as grey-listing, on your mail
-    server you should whitelist the sending email (controlled by `reportform` configuration option) to ensure your email is not discarded as spam.
+    If you are using anti-spam controls such as grey-listing on your mail
+    server, you should whitelist the sending email address (controlled by
+    `reportform` configuration option) to ensure your email is not discarded as spam.
     "
 
   # Find all matching messages.
diff --git a/lib/puppet/type.rb b/lib/puppet/type.rb
index 15f340f55..4472387d1 100644
--- a/lib/puppet/type.rb
+++ b/lib/puppet/type.rb
@@ -980,7 +980,7 @@ class Type
 
   newmetaparam(:audit) do
     desc "Marks a subset of this resource's unmanaged attributes for auditing. Accepts an
-      attribute name or a list of attribute names.
+      attribute name, an array of attribute names, or `all`.
 
       Auditing a resource attribute has two effects: First, whenever a catalog
       is applied with puppet apply or puppet agent, Puppet will check whether
diff --git a/lib/puppet/type/file/content.rb b/lib/puppet/type/file/content.rb
index 827183213..93b8e6913 100755
--- a/lib/puppet/type/file/content.rb
+++ b/lib/puppet/type/file/content.rb
@@ -16,8 +16,10 @@ module Puppet
     attr_reader :actual_content
 
     desc "Specify the contents of a file as a string.  Newlines, tabs, and
-      spaces can be specified using the escaped syntax (e.g., \\n for a newline).  The primary purpose of this parameter is to provide a
-      kind of limited templating:
+      spaces can be specified using standard escaped syntax in
+      double-quoted strings (e.g., \\n for a newline).
+
+      With very small files, you can construct strings directly...
 
           define resolve(nameserver1, nameserver2, domain, search) {
               $str = \"search $search
@@ -31,7 +33,9 @@ module Puppet
               }
           }
 
-      This attribute is especially useful when used with templating."
+      ...but for larger files, this attribute is more useful when combined with the
+      [template](http://docs.puppetlabs.com/references/latest/function.html#template)
+      function."
 
     # Store a checksum as the value, rather than the actual content.
     # Simplifies everything.