Add description as comment in crontab

Adds a desc to a job that will be output as a comment above the cron
entry in the crontab. It supports single line and multiline
descriptions.

Author: dyson

README.md

@@ -180,6 +180,26 @@ every 3.hours do
 end
 ```
 
+### Adding comments to crontab
+
+A description can be added to a job that will be included in the crontab as a comment above the cron entry.
+
+Example: A single line description:
+
+```ruby
+every 1.hours, description: "My job description" do
+  command "/usr/bin/my_great_command"
+end
+```
+
+Example: A multi line description:
+
+```ruby
+every 1.hours, description: "My job description\nhas multiple lines" do
+  command "/usr/bin/my_great_command"
+end
+```
+
 ### Capistrano integration
 
 Use the built-in Capistrano recipe for easy crontab updates with deploys. For Capistrano V3, see the next section.

lib/whenever/job.rb

@@ -2,7 +2,7 @@
 
 module Whenever
   class Job
-    attr_reader :at, :roles, :mailto
+    attr_reader :at, :roles, :mailto, :description
 
     def initialize(options = {})
       @options = options
@@ -11,6 +11,7 @@ def initialize(options = {})
       @mailto                           = options.fetch(:mailto, :default_mailto)
       @job_template                     = options.delete(:job_template) || ":job"
       @roles                            = Array(options.delete(:roles))
+      @description                      = options.delete(:description)
       @options[:output]                 = options.has_key?(:output) ? Whenever::Output::Redirection.new(options[:output]).to_s : ''
       @options[:environment_variable] ||= "RAILS_ENV"
       @options[:environment]          ||= :production

lib/whenever/job_list.rb

@@ -144,6 +144,7 @@ def cron_jobs_of_time(time, jobs)
         end
         Whenever::Output::Cron.output(time, job, :chronic_options => @chronic_options) do |cron|
           cron << "\n\n"
+          cron = (job.description.strip + "\n").gsub(/^(.*)$/, '# \1') + cron unless job.description.to_s.empty?
 
           if cron[0,1] == "@"
             shortcut_jobs << cron

test/functional/output_description_test.rb

@@ -0,0 +1,25 @@
+require 'test_helper'
+
+class OutputDescriptionTest < Whenever::TestCase
+  test "single line description" do
+    output = Whenever.cron \
+    <<-file
+      every "weekday", :description => "A description" do
+        command "blahblah"
+      end
+    file
+
+    assert_match "# A description\n0 0 * * 1-5 /bin/bash -l -c 'blahblah'\n\n", output
+  end
+
+  test "multi line description" do
+    output = Whenever.cron \
+    <<-file
+      every "weekday", :description => "A description\nhas mulitple lines" do
+        command "blahblah"
+      end
+    file
+
+    assert_match "# A description\n# has mulitple lines\n0 0 * * 1-5 /bin/bash -l -c 'blahblah'\n\n", output
+  end
+end