Clarify task_timer table comments (#15241)

### Description
Update `task_timer` table comments to aid future investigation into `TaskTimers`. 
Also added code comments at the top of the class to reference the wiki.

Based on [Hunter's investigation](https://hackmd.io/@hschallh/HJ62FbTNP); motivated by [PendingIncompleteAndUncancelledTaskTimersChecker warnings](https://dsva.slack.com/archives/CJL810329/p1599828304030800).

Prior comments were general from the perspective of `Asyncable` class. New comments provide more detail specific to `TaskTimers`.

### Acceptance Criteria
- [ ] Code compiles correctly

### Testing Plan
See Database Changes section below.

### Code Documentation Updates
- [x] Add or update code comments at the top of the class, module, and/or component.

### Database Changes
*Only for Schema Changes*

* [ ] ~Timestamps (created_at, updated_at) for new tables~
* [x] Column comments updated
* [x] Have your migration classes inherit from `Caseflow::Migration`, especially when adding indexes (use `add_safe_index`)
* [x] Verify that `migrate:rollback` works as desired ([`change` supported functions](https://edgeguides.rubyonrails.org/active_record_migrations.html#using-the-change-method))
* [ ] ~Query profiling performed (eyeball Rails log, check bullet and fasterer output)~
* [ ] ~Appropriate indexes added (especially for foreign keys, polymorphic columns, unique constraints, and Rails scopes)~
* [x] DB schema docs updated with `make docs` (after running `make migrate`)
* [x] #appeals-schema notified with summary and link to this PR

app/models/concerns/timeable_task.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+##
+# See https://github.com/department-of-veterans-affairs/caseflow/wiki/Timed-Tasks#timeabletask
+
 module TimeableTask
   extend ActiveSupport::Concern
 

app/models/task_timer.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+##
+# See https://github.com/department-of-veterans-affairs/caseflow/wiki/Timed-Tasks#tasktimer
+
 class TaskTimer < CaseflowRecord
   belongs_to :task
   include Asyncable

app/models/tasks/timed_hold_task.rb

@@ -2,6 +2,7 @@
 
 ##
 # Task that places parent task on hold for specified length of time. Holds expire through the TaskTimerJob.
+# https://github.com/department-of-veterans-affairs/caseflow/wiki/Timed-Tasks#timedholdtask
 
 class TimedHoldTask < Task
   include TimeableTask

db/migrate/20200915143743_edit_task_timers_comments.rb

@@ -0,0 +1,18 @@
+class EditTaskTimersComments < Caseflow::Migration
+  def up
+    change_table_comment :task_timers, "A task timer allows an associated task's (like EvidenceSubmissionWindowTask and TimedHoldTask) `when_timer_ends` method to be run asynchronously after timer expires."
+    change_column_comment :task_timers, :attempted_at, "Async timestamp for most recent attempt to run Task#when_timer_ends."
+    change_column_comment :task_timers, :canceled_at, "Timestamp when job was abandoned. Associated task is typically cancelled."
+    change_column_comment :task_timers, :last_submitted_at, "Async timestamp for most recent job start. Initially set to when timer should expire (Task#timer_ends_at)."
+    change_column_comment :task_timers, :processed_at, "Async timestamp for when the job completes successfully. Associated task's method Task#when_timer_ends ran successfully."
+    change_column_comment :task_timers, :task_id, "ID of the associated Task to be run."
+  end
+  def down
+    change_table_comment :task_timers, "Task timers allow tasks to be run asynchronously after some future date, like EvidenceSubmissionWindowTask."
+    change_column_comment :task_timers, :attempted_at, "Async timestamp for most recent attempt to run."
+    change_column_comment :task_timers, :canceled_at, "Timestamp when job was abandoned"
+    change_column_comment :task_timers, :last_submitted_at, "Async timestamp for most recent job start."
+    change_column_comment :task_timers, :processed_at, "Async timestamp for when the job completes successfully."
+    change_column_comment :task_timers, :task_id, "ID of the Task to be run."
+  end
+end

db/schema.rb

@@ -10,7 +10,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
 
-ActiveRecord::Schema.define(version: 2020_09_08_191436) do
+ActiveRecord::Schema.define(version: 2020_09_15_143743) do
 
   # These are extensions that must be enabled in order to support this database
   enable_extension "plpgsql"
@@ -1265,15 +1265,15 @@
     t.index ["updated_at"], name: "index_tags_on_updated_at"
   end
 
-  create_table "task_timers", comment: "Task timers allow tasks to be run asynchronously after some future date, like EvidenceSubmissionWindowTask.", force: :cascade do |t|
-    t.datetime "attempted_at", comment: "Async timestamp for most recent attempt to run."
-    t.datetime "canceled_at", comment: "Timestamp when job was abandoned"
+  create_table "task_timers", comment: "A task timer allows an associated task's (like EvidenceSubmissionWindowTask and TimedHoldTask) `when_timer_ends` method to be run asynchronously after timer expires.", force: :cascade do |t|
+    t.datetime "attempted_at", comment: "Async timestamp for most recent attempt to run Task#when_timer_ends."
+    t.datetime "canceled_at", comment: "Timestamp when job was abandoned. Associated task is typically cancelled."
     t.datetime "created_at", null: false, comment: "Automatic timestamp for record creation."
     t.string "error", comment: "Async any error message from most recent failed attempt to run."
-    t.datetime "last_submitted_at", comment: "Async timestamp for most recent job start."
-    t.datetime "processed_at", comment: "Async timestamp for when the job completes successfully."
+    t.datetime "last_submitted_at", comment: "Async timestamp for most recent job start. Initially set to when timer should expire (Task#timer_ends_at)."
+    t.datetime "processed_at", comment: "Async timestamp for when the job completes successfully. Associated task's method Task#when_timer_ends ran successfully."
     t.datetime "submitted_at", comment: "Async timestamp for initial job start."
-    t.bigint "task_id", null: false, comment: "ID of the Task to be run."
+    t.bigint "task_id", null: false, comment: "ID of the associated Task to be run."
     t.datetime "updated_at", null: false, comment: "Automatic timestmap for record update."
     t.index ["task_id"], name: "index_task_timers_on_task_id"
     t.index ["updated_at"], name: "index_task_timers_on_updated_at"

docs/schema/caseflow.csv

@@ -987,16 +987,16 @@ tasks,started_at,datetime,,,,,,
 tasks,status,string ∗,x,,,,x,
 tasks,type,string ∗,x,,,,x,
 tasks,updated_at,datetime ∗,x,,,,x,
-task_timers,,,,,,,,"Task timers allow tasks to be run asynchronously after some future date, like EvidenceSubmissionWindowTask."
-task_timers,attempted_at,datetime,,,,,,Async timestamp for most recent attempt to run.
-task_timers,canceled_at,datetime,,,,,,Timestamp when job was abandoned
+task_timers,,,,,,,,A task timer allows an associated task's (like EvidenceSubmissionWindowTask and TimedHoldTask) `when_timer_ends` method to be run asynchronously after timer expires.
+task_timers,attempted_at,datetime,,,,,,Async timestamp for most recent attempt to run Task#when_timer_ends.
+task_timers,canceled_at,datetime,,,,,,Timestamp when job was abandoned. Associated task is typically cancelled.
 task_timers,created_at,datetime ∗,x,,,,,Automatic timestamp for record creation.
 task_timers,error,string,,,,,,Async any error message from most recent failed attempt to run.
 task_timers,id,integer (8) PK,x,x,,,,
-task_timers,last_submitted_at,datetime,,,,,,Async timestamp for most recent job start.
-task_timers,processed_at,datetime,,,,,,Async timestamp for when the job completes successfully.
+task_timers,last_submitted_at,datetime,,,,,,Async timestamp for most recent job start. Initially set to when timer should expire (Task#timer_ends_at).
+task_timers,processed_at,datetime,,,,,,Async timestamp for when the job completes successfully. Associated task's method Task#when_timer_ends ran successfully.
 task_timers,submitted_at,datetime,,,,,,Async timestamp for initial job start.
-task_timers,task_id,integer (8) ∗ FK,x,,x,,x,ID of the Task to be run.
+task_timers,task_id,integer (8) ∗ FK,x,,x,,x,ID of the associated Task to be run.
 task_timers,updated_at,datetime ∗,x,,,,x,Automatic timestmap for record update.
 team_quotas,,,,,,,,
 team_quotas,created_at,datetime ∗,x,,,,,