Add description as comment in crontab

README.md

@@ -175,6 +175,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, desc: "My job description" do
+  command "/usr/bin/my_great_command"
+end
+```
+
+Example: A multi line description:
+
+```ruby
+every 1.hours, desc: "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, :desc
 
     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))
+      @desc                             = options.delete(:desc)
       @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.desc.strip + "\n").gsub(/^(.*)$/, '# \1') + cron unless job.desc.to_s.empty?
 
           if cron[0,1] == "@"
             shortcut_jobs << cron

test/functional/output_desc_test.rb

@@ -0,0 +1,25 @@
+require 'test_helper'
+
+class OutputDescTest < Whenever::TestCase
+  test "single line description" do
+    output = Whenever.cron \
+    <<-file
+      every "weekday", :desc => "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", :desc => "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