diff --git a/src/timer/timer_game_calendar.cpp b/src/timer/timer_game_calendar.cpp
index 8a23b85674..b90b0c765e 100644
--- a/src/timer/timer_game_calendar.cpp
+++ b/src/timer/timer_game_calendar.cpp
@@ -10,6 +10,16 @@
  * This file implements the timer logic for the game-calendar-timer.
  */
 
+/**
+ * Calendar time is used for technology and time-of-year changes, including:
+ * - Vehicle, airport, station, object introduction and obsolescence
+ * - Vehicle and engine age
+ * - NewGRF variables for visual styles or behavior based on year or time of year (e.g. variable snow line)
+ * - Inflation, since it is tied to original game years. One interpretation of inflation is that it compensates for faster and higher capacity vehicles,
+ *   another is that it compensates for more established companies. Each of these point to a different choice of calendar versus economy time, but we have to pick one
+ *   so we follow a previous decision to tie inflation to original TTD game years.
+ */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "timer.h"
diff --git a/src/timer/timer_game_economy.cpp b/src/timer/timer_game_economy.cpp
index 010043e21a..308ad9e57f 100644
--- a/src/timer/timer_game_economy.cpp
+++ b/src/timer/timer_game_economy.cpp
@@ -10,6 +10,19 @@
  * This file implements the timer logic for the game-economy-timer.
  */
 
+/**
+ * Economy time is used for the regular pace of the game, including:
+ * - Industry and house production/consumption
+ * - Industry production changes, closure, and spawning
+ * - Town growth
+ * - Company age and financial statistics
+ * - Vehicle financial statistics
+ * - Vehicle aging, depreciation, reliability, and renewal
+ * - Payment intervals for running and maintenance costs, loan interest, etc.
+ * - Cargo payment "time" calculation
+ * - Local authority and station ratings change intervals
+ */
+
 #include "../stdafx.h"
 #include "../openttd.h"
 #include "timer.h"