(#3553) Explain that cron resources require time attributes

The cron resource docs previously read, "All fields except the command and the
user are optional, although specifying no periodic fields would result in the
command being executed every minute." This was factually incorrect; instead,
specifying no periodic fields results in a failure and an unhelpful error on
Puppet 2.6 and 2.7.

Although the issue will remain open as a behavior bug, this commit corrects
the documentation of which attributes are required. It also changes the @doc
string to a heredoc to simplify quote escaping.

1 files changed, 13 insertions, 12 deletions

diff --git a/lib/puppet/type/cron.rb b/lib/puppet/type/cron.rb
index 4f6ea733c..5367517b2 100755
--- a/lib/puppet/type/cron.rb
+++ b/lib/puppet/type/cron.rb
@@ -3,11 +3,12 @@ require 'facter'
 require 'puppet/util/filetype'
 
 Puppet::Type.newtype(:cron) do
-  @doc = "Installs and manages cron jobs.  All fields except the command
-    and the user are optional, although specifying no periodic
-    fields would result in the command being executed every
-    minute.  While the name of the cron job is not part of the actual
-    job, it is used by Puppet to store and retrieve it.
+  @doc = <<-EOT
+    Installs and manages cron jobs.  Every cron resource requires a command
+    and user attribute, as well as at least one periodic attribute (hour,
+    minute, month, monthday, weekday, or special).  While the name of the cron
+    job is not part of the actual job, it is used by Puppet to store and
+    retrieve it.
 
     If you specify a cron job that matches an existing job in every way
     except name, then the jobs will be considered equivalent and the
@@ -18,30 +19,30 @@ Puppet::Type.newtype(:cron) do
     Example:
 
         cron { logrotate:
-          command => \"/usr/sbin/logrotate\",
+          command => "/usr/sbin/logrotate",
           user => root,
           hour => 2,
           minute => 0
         }
 
-    Note that all cron values can be specified as an array of values:
+    Note that all periodic attributes can be specified as an array of values:
 
         cron { logrotate:
-          command => \"/usr/sbin/logrotate\",
+          command => "/usr/sbin/logrotate",
           user => root,
           hour => [2, 4]
         }
 
-    Or using ranges, or the step syntax `*/2` (although there's no guarantee that
-    your `cron` daemon supports it):
+    ...or using ranges or the step syntax `*/2` (although there's no guarantee
+    that your `cron` daemon supports these):
 
         cron { logrotate:
-          command => \"/usr/sbin/logrotate\",
+          command => "/usr/sbin/logrotate",
           user => root,
           hour => ['2-4'],
           minute => '*/10'
         }
-    "
+  EOT
   ensurable
 
   # A base class for all of the Cron parameters, since they all have