From dc22edc556965591958b996e7777580062f46861 Mon Sep 17 00:00:00 2001
From: frosch <frosch@openttd.org>
Date: Sat, 23 Mar 2024 21:34:31 +0100
Subject: [PATCH] Doc: [Script] Extend API documentation on calendar- vs
 economy-time

---
 src/script/api/script_airport.hpp        |  3 +-
 src/script/api/script_basestation.hpp    |  5 +-
 src/script/api/script_client.hpp         |  5 +-
 src/script/api/script_company.hpp        | 43 ++++++++++--------
 src/script/api/script_date.hpp           | 24 ++++++++++
 src/script/api/script_engine.hpp         | 13 +++---
 src/script/api/script_event_types.hpp    |  4 +-
 src/script/api/script_group.hpp          |  6 ++-
 src/script/api/script_industry.hpp       | 30 +++++++-----
 src/script/api/script_infrastructure.hpp |  9 ++--
 src/script/api/script_order.hpp          |  4 +-
 src/script/api/script_story_page.hpp     |  6 ++-
 src/script/api/script_subsidy.hpp        |  7 +--
 src/script/api/script_town.hpp           | 58 +++++++++++++++---------
 src/script/api/script_vehicle.hpp        | 26 ++++++-----
 15 files changed, 154 insertions(+), 89 deletions(-)

diff --git a/src/script/api/script_airport.hpp b/src/script/api/script_airport.hpp
index e46658219a..cb3fc3c227 100644
--- a/src/script/api/script_airport.hpp
+++ b/src/script/api/script_airport.hpp
@@ -204,7 +204,8 @@ public:
 	 * Get the monthly maintenance cost of an airport type.
 	 * @param type The airport type to get the monthly maintenance cost of.
 	 * @pre IsAirportInformationAvailable(type)
-	 * @return Monthly maintenance cost of the airport type.
+	 * @return Maintenance cost of the airport type per economy-month.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetMonthlyMaintenanceCost(AirportType type);
 
diff --git a/src/script/api/script_basestation.hpp b/src/script/api/script_basestation.hpp
index 52df57f78c..cf6388f327 100644
--- a/src/script/api/script_basestation.hpp
+++ b/src/script/api/script_basestation.hpp
@@ -68,9 +68,10 @@ public:
 	static TileIndex GetLocation(StationID station_id);
 
 	/**
-	 * Get the last date a station part was added to this station.
+	 * Get the last calendar-date a station part was added to this station.
 	 * @param station_id The station to look at.
-	 * @return The last date some part of this station was build.
+	 * @return The last calendar-date some part of this station was build.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static ScriptDate::Date GetConstructionDate(StationID station_id);
 };
diff --git a/src/script/api/script_client.hpp b/src/script/api/script_client.hpp
index 7b5d6f5dc3..7e463e4f94 100644
--- a/src/script/api/script_client.hpp
+++ b/src/script/api/script_client.hpp
@@ -56,10 +56,11 @@ public:
 	static ScriptCompany::CompanyID GetCompany(ClientID client);
 
 	/**
-	 * Get the game date when the given client has joined.
+	 * Get the economy-date when the given client has joined.
 	 * @param client The client to get joining date for.
 	 * @pre ResolveClientID(client) != CLIENT_INVALID.
-	 * @return The date when client has joined.
+	 * @return The economy-date when client has joined.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static ScriptDate::Date GetJoinDate(ClientID client);
 };
diff --git a/src/script/api/script_company.hpp b/src/script/api/script_company.hpp
index ab330296c6..e5dad4c194 100644
--- a/src/script/api/script_company.hpp
+++ b/src/script/api/script_company.hpp
@@ -281,59 +281,64 @@ public:
 	static bool ChangeBankBalance(CompanyID company, Money delta, ExpensesType expenses_type, TileIndex tile);
 
 	/**
-	 * Get the income of the company in the given quarter.
+	 * Get the income of the company in the given economy-quarter.
 	 * Note that this function only considers recurring income from vehicles;
 	 * it does not include one-time income from selling stuff.
 	 * @param company The company to get the quarterly income of.
-	 * @param quarter The quarter to get the income of.
+	 * @param quarter The economy-quarter to get the income of.
 	 * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 	 * @pre quarter <= EARLIEST_QUARTER.
-	 * @return The gross income of the company in the given quarter.
+	 * @return The gross income of the company in the given economy-quarter.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetQuarterlyIncome(CompanyID company, SQInteger quarter);
 
 	/**
-	 * Get the expenses of the company in the given quarter.
+	 * Get the expenses of the company in the given economy-quarter.
 	 * Note that this function only considers recurring expenses from vehicle
 	 * running cost, maintenance and interests; it does not include one-time
 	 * expenses from construction and buying stuff.
 	 * @param company The company to get the quarterly expenses of.
-	 * @param quarter The quarter to get the expenses of.
+	 * @param quarter The economy-quarter to get the expenses of.
 	 * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 	 * @pre quarter <= EARLIEST_QUARTER.
-	 * @return The expenses of the company in the given quarter.
+	 * @return The expenses of the company in the given economy-quarter.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetQuarterlyExpenses(CompanyID company, SQInteger quarter);
 
 	/**
-	 * Get the amount of cargo delivered by the given company in the given quarter.
+	 * Get the amount of cargo delivered by the given company in the given economy-quarter.
 	 * @param company The company to get the amount of delivered cargo of.
-	 * @param quarter The quarter to get the amount of delivered cargo of.
+	 * @param quarter The economy-quarter to get the amount of delivered cargo of.
 	 * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 	 * @pre quarter <= EARLIEST_QUARTER.
-	 * @return The amount of cargo delivered by the given company in the given quarter.
+	 * @return The amount of cargo delivered by the given company in the given economy-quarter.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetQuarterlyCargoDelivered(CompanyID company, SQInteger quarter);
 
 	/**
-	 * Get the performance rating of the given company in the given quarter.
+	 * Get the performance rating of the given company in the given economy-quarter.
 	 * @param company The company to get the performance rating of.
-	 * @param quarter The quarter to get the performance rating of.
+	 * @param quarter The economy-quarter to get the performance rating of.
 	 * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 	 * @pre quarter <= EARLIEST_QUARTER.
 	 * @pre quarter != CURRENT_QUARTER.
-	 * @note The performance rating is calculated after every quarter, so the value for CURRENT_QUARTER is undefined.
-	 * @return The performance rating of the given company in the given quarter.
+	 * @note The performance rating is calculated after every economy-quarter, so the value for CURRENT_QUARTER is undefined.
+	 * @return The performance rating of the given company in the given economy-quarter.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetQuarterlyPerformanceRating(CompanyID company, SQInteger quarter);
 
 	/**
-	 * Get the value of the company in the given quarter.
+	 * Get the value of the company in the given economy-quarter.
 	 * @param company The company to get the value of.
-	 * @param quarter The quarter to get the value of.
+	 * @param quarter The economy-quarter to get the value of.
 	 * @pre ResolveCompanyID(company) != COMPANY_INVALID.
 	 * @pre quarter <= EARLIEST_QUARTER.
-	 * @return The value of the company in the given quarter.
+	 * @return The value of the company in the given economy-quarter.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetQuarterlyCompanyValue(CompanyID company, SQInteger quarter);
 
@@ -377,10 +382,11 @@ public:
 
 	/**
 	 * Set the number of months before/after max age to autorenew an engine for your company.
-	 * @param months The new months between autorenew.
+	 * @param months The number of calendar-months before/after max age of engine.
 	 *               The value will be clamped to MIN(int16_t) .. MAX(int16_t).
 	 * @game @pre ScriptCompanyMode::IsValid().
 	 * @return True if autorenew months has been modified.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static bool SetAutoRenewMonths(SQInteger months);
 
@@ -388,7 +394,8 @@ public:
 	 * Return the number of months before/after max age to autorenew an engine for a company.
 	 * @param company The company to get the autorenew months of.
 	 * @pre ResolveCompanyID(company) != COMPANY_INVALID.
-	 * @return The months before/after max age of engine.
+	 * @return The number of calendar-months before/after max age of engine.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static SQInteger GetAutoRenewMonths(CompanyID company);
 
diff --git a/src/script/api/script_date.hpp b/src/script/api/script_date.hpp
index 5c7ddec042..44f609d80b 100644
--- a/src/script/api/script_date.hpp
+++ b/src/script/api/script_date.hpp
@@ -23,6 +23,30 @@
  * @note Dates can be used to determine the number of days between
  *       two different moments in time because they count the number
  *       of days since the year 0.
+ *
+ * \anchor ScriptCalendarTime
+ * \b Calendar-Time
+ *
+ * Calendar time measures the technological progression in the game.
+ * \li The calendar date is shown in the status bar.
+ * \li The calendar date affects engine model introduction and expiration.
+ * \li Progression of calendar time can be slowed or even halted via game settings.
+ *
+ * Calendar time uses the Gregorian calendar with 365 or 366 days per year.
+ *
+ * \anchor ScriptEconomyTime
+ * \b Economy-Time
+ *
+ * Economy time measures the in-game time progression, while the game is not paused.
+ * \li Cargo production and consumption follows economy time.
+ * \li Recurring income and expenses follow economy time.
+ * \li Production and income statistics and balances are created per economy month/quarter/year.
+ *
+ * Depending on game settings economy time is represented differently:
+ * \li Calendar-based timekeeping: Economy- and calendar-time use the identical Gregorian calendar.
+ * \li Wallclock-based timekeeping: Economy- and calendar-time are separate.
+ *     Economy-time will use a 360 day calendar (12 months with 30 days each), which runs at a constant speed of one economy-month per realtime-minute.
+ *     Calendar-time will use a Gregorian calendar, which can be slowed to stopped via game settings.
  */
 class ScriptDate : public ScriptObject {
 public:
diff --git a/src/script/api/script_engine.hpp b/src/script/api/script_engine.hpp
index 2baed5bec3..a8ad60d0ac 100644
--- a/src/script/api/script_engine.hpp
+++ b/src/script/api/script_engine.hpp
@@ -125,8 +125,8 @@ public:
 	 * Get the maximum age of a brand new engine.
 	 * @param engine_id The engine to get the maximum age of.
 	 * @pre IsValidEngine(engine_id).
-	 * @returns The maximum age of a new engine in days.
-	 * @note Age is in days; divide by 366 to get per year.
+	 * @returns The maximum age of a new engine in calendar-days.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static SQInteger GetMaxAge(EngineID engine_id);
 
@@ -134,8 +134,8 @@ public:
 	 * Get the running cost of an engine.
 	 * @param engine_id The engine to get the running cost of.
 	 * @pre IsValidEngine(engine_id).
-	 * @return The running cost of a vehicle per year.
-	 * @note Cost is per year; divide by 365 to get per day.
+	 * @return The running cost of a vehicle per economy-year.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetRunningCost(EngineID engine_id);
 
@@ -167,10 +167,11 @@ public:
 	static SQInteger GetMaxTractiveEffort(EngineID engine_id);
 
 	/**
-	 * Get the date this engine was designed.
+	 * Get the calendar-date this engine was designed.
 	 * @param engine_id The engine to get the design date of.
 	 * @pre IsValidEngine(engine_id).
-	 * @return The date this engine was designed.
+	 * @return The calendar-date this engine was designed.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static ScriptDate::Date GetDesignDate(EngineID engine_id);
 
diff --git a/src/script/api/script_event_types.hpp b/src/script/api/script_event_types.hpp
index da9cdf3a6d..8142893d11 100644
--- a/src/script/api/script_event_types.hpp
+++ b/src/script/api/script_event_types.hpp
@@ -272,8 +272,8 @@ public:
 
 	/**
 	 * Get the running cost of the offered engine.
-	 * @return The running cost of the vehicle per year.
-	 * @note Cost is per year; divide by 365 to get per day.
+	 * @return The running cost of the vehicle per economy-year.
+	 * @see \ref ScriptEconomyTime
 	 */
 	Money GetRunningCost();
 
diff --git a/src/script/api/script_group.hpp b/src/script/api/script_group.hpp
index 153fff3279..9b7da3e90b 100644
--- a/src/script/api/script_group.hpp
+++ b/src/script/api/script_group.hpp
@@ -222,7 +222,8 @@ public:
 	 * Get the current profit of a group.
 	 * @param group_id The group to get the profit of.
 	 * @pre IsValidGroup(group_id).
-	 * @return The current profit the group has.
+	 * @return The profit the vehicles in this group have made this economy-year so far.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetProfitThisYear(GroupID group_id);
 
@@ -230,7 +231,8 @@ public:
 	 * Get the profit of last year of a group.
 	 * @param group_id The group to get the profit of.
 	 * @pre IsValidGroup(group_id).
-	 * @return The current profit the group had last year.
+	 * @return The profit the vehicles in this group  made in the previous economy-year.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetProfitLastYear(GroupID group_id);
 
diff --git a/src/script/api/script_industry.hpp b/src/script/api/script_industry.hpp
index 3bca023d56..72f144663e 100644
--- a/src/script/api/script_industry.hpp
+++ b/src/script/api/script_industry.hpp
@@ -86,10 +86,11 @@ public:
 	static std::optional<std::string> GetName(IndustryID industry_id);
 
 	/**
-	 * Get the construction date of an industry.
+	 * Get the construction calendar-date of an industry.
 	 * @param industry_id The index of the industry.
 	 * @pre IsValidIndustry(industry_id).
-	 * @return Date the industry was constructed.
+	 * @return Calendar-date the industry was constructed.
+	 * @see \ref ScriptCalendarTime
 	 * @api -ai
 	 */
 	static ScriptDate::Date GetConstructionDate(IndustryID industry_id);
@@ -126,32 +127,35 @@ public:
 	static SQInteger GetStockpiledCargo(IndustryID industry_id, CargoID cargo_id);
 
 	/**
-	 * Get the total last month's production of the given cargo at an industry.
+	 * Get the total last economy-month's production of the given cargo at an industry.
 	 * @param industry_id The index of the industry.
 	 * @param cargo_id The index of the cargo.
 	 * @pre IsValidIndustry(industry_id).
 	 * @pre ScriptCargo::IsValidCargo(cargo_id).
-	 * @return The last month's production of the given cargo for this industry.
+	 * @return The last economy-month's production of the given cargo for this industry.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetLastMonthProduction(IndustryID industry_id, CargoID cargo_id);
 
 	/**
-	 * Get the total amount of cargo transported from an industry last month.
+	 * Get the total amount of cargo transported from an industry last economy-month.
 	 * @param industry_id The index of the industry.
 	 * @param cargo_id The index of the cargo.
 	 * @pre IsValidIndustry(industry_id).
 	 * @pre ScriptCargo::IsValidCargo(cargo_id).
-	 * @return The amount of given cargo transported from this industry last month.
+	 * @return The amount of given cargo transported from this industry last economy-month.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetLastMonthTransported(IndustryID industry_id, CargoID cargo_id);
 
 	/**
-	 * Get the percentage of cargo transported from an industry last month.
+	 * Get the percentage of cargo transported from an industry last economy-month.
 	 * @param industry_id The index of the industry.
 	 * @param cargo_id The index of the cargo.
 	 * @pre IsValidIndustry(industry_id).
 	 * @pre ScriptCargo::IsValidCargo(cargo_id).
-	 * @return The percentage of given cargo transported from this industry last month.
+	 * @return The percentage of given cargo transported from this industry last economy-month.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetLastMonthTransportedPercentage(IndustryID industry_id, CargoID cargo_id);
 
@@ -246,21 +250,23 @@ public:
 	static IndustryType GetIndustryType(IndustryID industry_id);
 
 	/**
-	 * Get the last year this industry had any production output.
+	 * Get the last economy-year this industry had any production output.
 	 * @param industry_id The index of the industry.
 	 * @pre IsValidIndustry(industry_id).
-	 * @return Year the industry last had production, 0 if error.
+	 * @return Economy-year the industry last had production, 0 if error.
+	 * @see \ref ScriptEconomyTime
 	 * @api -ai
 	 */
 	static SQInteger GetLastProductionYear(IndustryID industry_id);
 
 	/**
-	 * Get the last date this industry accepted any cargo delivery.
+	 * Get the last economy-date this industry accepted any cargo delivery.
 	 * @param industry_id The index of the industry.
 	 * @param cargo_type The cargo to query, or INVALID_CARGO to query latest of all accepted cargoes.
 	 * @pre IsValidIndustry(industry_id).
 	 * @pre IsValidCargo(cargo_type) || cargo_type == INVALID_CARGO.
-	 * @return Date the industry last received cargo from a delivery, or ScriptDate::DATE_INVALID on error.
+	 * @return Economy-date the industry last received cargo from a delivery, or ScriptDate::DATE_INVALID on error.
+	 * @see \ref ScriptEconomyTime
 	 * @api -ai
 	 */
 	static ScriptDate::Date GetCargoLastAcceptedDate(IndustryID industry_id, CargoID cargo_type);
diff --git a/src/script/api/script_infrastructure.hpp b/src/script/api/script_infrastructure.hpp
index 9b3a499b7d..79ced1b586 100644
--- a/src/script/api/script_infrastructure.hpp
+++ b/src/script/api/script_infrastructure.hpp
@@ -58,7 +58,8 @@ public:
 	 * Return the monthly maintenance costs of a specific rail type for a company.
 	 * @param company The company to get the monthly cost for.
 	 * @param railtype Rail type to get the cost of.
-	 * @return Monthly maintenance cost for the rail type.
+	 * @return Maintenance cost for the rail type per economy-month.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetMonthlyRailCosts(ScriptCompany::CompanyID company, ScriptRail::RailType railtype);
 
@@ -66,7 +67,8 @@ public:
 	 * Return the monthly maintenance costs of a specific road type for a company.
 	 * @param company The company to get the monthly cost for.
 	 * @param roadtype Road type to get the cost of.
-	 * @return Monthly maintenance cost for the road type.
+	 * @return Maintenance cost for the road type per economy-month.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetMonthlyRoadCosts(ScriptCompany::CompanyID company, ScriptRoad::RoadType roadtype);
 
@@ -74,8 +76,9 @@ public:
 	 * Return the monthly maintenance costs of an infrastructure category for a company.
 	 * @param company The company to get the monthly cost for.
 	 * @param infra_type Infrastructure category to get the cost of.
-	 * @return Monthly maintenance cost for the wanted category.
+	 * @return Maintenance cost for the wanted category per economy-month.
 	 * @note #INFRASTRUCTURE_RAIL and #INFRASTRUCTURE_ROAD return the total cost for all rail/road types.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetMonthlyInfrastructureCosts(ScriptCompany::CompanyID company, Infrastructure infra_type);
 };
diff --git a/src/script/api/script_order.hpp b/src/script/api/script_order.hpp
index 752136134e..68cc756cb2 100644
--- a/src/script/api/script_order.hpp
+++ b/src/script/api/script_order.hpp
@@ -93,10 +93,10 @@ public:
 		OC_RELIABILITY         = ::OCV_RELIABILITY,        ///< Skip based on the reliability, value is percent (0..100).
 		OC_MAX_RELIABILITY     = ::OCV_MAX_RELIABILITY,    ///< Skip based on the maximum reliability.  Value in percent
 		OC_MAX_SPEED           = ::OCV_MAX_SPEED,          ///< Skip based on the maximum speed, value is in OpenTTD's internal speed unit, see ScriptEngine::GetMaxSpeed.
-		OC_AGE                 = ::OCV_AGE,                ///< Skip based on the age, value is in years.
+		OC_AGE                 = ::OCV_AGE,                ///< Skip based on the age, value is in calender-years. @see \ref ScriptCalendarTime
 		OC_REQUIRES_SERVICE    = ::OCV_REQUIRES_SERVICE,   ///< Skip when the vehicle requires service, no value.
 		OC_UNCONDITIONALLY     = ::OCV_UNCONDITIONALLY,    ///< Always skip, no compare function, no value.
-		OC_REMAINING_LIFETIME  = ::OCV_REMAINING_LIFETIME, ///< Skip based on the remaining lifetime
+		OC_REMAINING_LIFETIME  = ::OCV_REMAINING_LIFETIME, ///< Skip based on the remaining lifetime in calendar-years. @see \ref ScriptCalendarTime
 
 		/* Custom added value, only valid for this API */
 		OC_INVALID             = -1,                       ///< An invalid condition, do not use.
diff --git a/src/script/api/script_story_page.hpp b/src/script/api/script_story_page.hpp
index a15af1dc4e..65ea06f29b 100644
--- a/src/script/api/script_story_page.hpp
+++ b/src/script/api/script_story_page.hpp
@@ -265,18 +265,20 @@ public:
 	/**
 	 * Get the page date which is displayed at the top of each page.
 	 * @param story_page_id The story page to get the date of.
-	 * @return The date
+	 * @return The calendar-date
 	 * @pre IsValidStoryPage(story_page_id).
+	 * @see \ref ScriptCalendarTime
 	 */
 	static ScriptDate::Date GetDate(StoryPageID story_page_id);
 
 	/**
 	 * Update date of a story page. The date is shown in the top left of the page
 	 * @param story_page_id The story page to set the date for.
-	 * @param date Date to display at the top of story page or ScriptDate::DATE_INVALID to disable showing date on this page. (also, @see ScriptDate)
+	 * @param date Calendar-date to display at the top of story page or ScriptDate::DATE_INVALID to disable showing date on this page. (also, @see ScriptDate)
 	 * @return True if the action succeeded.
 	 * @pre ScriptCompanyMode::IsDeity().
 	 * @pre IsValidStoryPage(story_page_id).
+	 * @see \ref ScriptCalendarTime
 	 */
 	static bool SetDate(StoryPageID story_page_id, ScriptDate::Date date);
 
diff --git a/src/script/api/script_subsidy.hpp b/src/script/api/script_subsidy.hpp
index 5bfcf1c9a2..4c139458f6 100644
--- a/src/script/api/script_subsidy.hpp
+++ b/src/script/api/script_subsidy.hpp
@@ -74,14 +74,15 @@ public:
 	static ScriptCompany::CompanyID GetAwardedTo(SubsidyID subsidy_id);
 
 	/**
-	 * Get the date this subsidy expires. In case the subsidy is already
-	 *  awarded, return the date the subsidy expires, else, return the date the
+	 * Get the economy-date this subsidy expires. In case the subsidy is already
+	 *  awarded, return the economy-date the subsidy expires, else, return the economy-date the
 	 *  offer expires.
 	 * @param subsidy_id The SubsidyID to check.
 	 * @pre IsValidSubsidy(subsidy_id).
-	 * @return The last valid date of this subsidy.
+	 * @return The last valid economy-date of this subsidy.
 	 * @note The return value of this function will change if the subsidy is
 	 *  awarded.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static ScriptDate::Date GetExpireDate(SubsidyID subsidy_id);
 
diff --git a/src/script/api/script_town.hpp b/src/script/api/script_town.hpp
index 0c13ef8914..ab2ce1f807 100644
--- a/src/script/api/script_town.hpp
+++ b/src/script/api/script_town.hpp
@@ -48,7 +48,8 @@ public:
 		TOWN_ACTION_ADVERTISE_LARGE  = 2,
 
 		/**
-		 * Rebuild the roads of this town for 6 months.
+		 * Rebuild the roads of this town for 6 economy-months.
+		 * @see \ref ScriptEconomyTime
 		 */
 		TOWN_ACTION_ROAD_REBUILD     = 3,
 
@@ -58,12 +59,14 @@ public:
 		TOWN_ACTION_BUILD_STATUE     = 4,
 
 		/**
-		 * Fund the creation of extra buildings for 3 months.
+		 * Fund the creation of extra buildings for 3 economy-months.
+		 * @see \ref ScriptEconomyTime
 		 */
 		TOWN_ACTION_FUND_BUILDINGS   = 5,
 
 		/**
-		 * Buy exclusive rights for this town for 12 months.
+		 * Buy exclusive rights for this town for 12 economy-months.
+		 * @see \ref ScriptEconomyTime
 		 */
 		TOWN_ACTION_BUY_RIGHTS       = 6,
 
@@ -191,92 +194,100 @@ public:
 	static TileIndex GetLocation(TownID town_id);
 
 	/**
-	 * Get the total last month's production of the given cargo at a town.
+	 * Get the total last economy-month's production of the given cargo at a town.
 	 * @param town_id The index of the town.
 	 * @param cargo_id The index of the cargo.
 	 * @pre IsValidTown(town_id).
 	 * @pre ScriptCargo::IsValidCargo(cargo_id).
-	 * @return The last month's production of the given cargo for this town.
+	 * @return The last economy-month's production of the given cargo for this town.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetLastMonthProduction(TownID town_id, CargoID cargo_id);
 
 	/**
-	 * Get the total amount of cargo supplied from a town last month.
+	 * Get the total amount of cargo supplied from a town last economy-month.
 	 * @param town_id The index of the town.
 	 * @param cargo_id The index of the cargo.
 	 * @pre IsValidTown(town_id).
 	 * @pre ScriptCargo::IsValidCargo(cargo_id).
-	 * @return The amount of cargo supplied for transport from this town last month.
+	 * @return The amount of cargo supplied for transport from this town last economy-month.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetLastMonthSupplied(TownID town_id, CargoID cargo_id);
 
 	/**
-	 * Get the percentage of transported production of the given cargo at a town.
+	 * Get the percentage of transported production of the given cargo at a town last economy-month.
 	 * @param town_id The index of the town.
 	 * @param cargo_id The index of the cargo.
 	 * @pre IsValidTown(town_id).
 	 * @pre ScriptCargo::IsValidCargo(cargo_id).
-	 * @return The percentage of given cargo transported from this town last month.
+	 * @return The percentage of given cargo transported from this town last economy-month.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetLastMonthTransportedPercentage(TownID town_id, CargoID cargo_id);
 
 	/**
-	 * Get the total amount of cargo effects received by a town last month.
+	 * Get the total amount of cargo effects received by a town last economy-month.
 	 * @param town_id The index of the town.
 	 * @param towneffect_id The index of the cargo.
 	 * @pre IsValidTown(town_id).
 	 * @pre ScriptCargo::IsValidTownEffect(cargo_id).
-	 * @return The amount of cargo received by this town last month for this cargo effect.
+	 * @return The amount of cargo received by this town last economy-month for this cargo effect.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetLastMonthReceived(TownID town_id, ScriptCargo::TownEffect towneffect_id);
 
 	/**
-	 * Set the goal of a cargo for this town.
+	 * Set the goal of a cargo per economy-month for this town.
 	 * @param town_id The index of the town.
 	 * @param towneffect_id The index of the towneffect.
-	 * @param goal The new goal.
+	 * @param goal The new goal amount for cargo delivered per economy-month.
 	 *             The value will be clamped to 0 .. MAX(uint32_t).
 	 * @pre IsValidTown(town_id).
 	 * @pre ScriptCargo::IsValidTownEffect(towneffect_id).
 	 * @pre ScriptCompanyMode::IsDeity().
 	 * @return True if the action succeeded.
+	 * @see \ref ScriptEconomyTime
 	 * @api -ai
 	 */
 	static bool SetCargoGoal(TownID town_id, ScriptCargo::TownEffect towneffect_id, SQInteger goal);
 
 	/**
-	 * Get the amount of cargo that needs to be delivered (per TownEffect) for a
+	 * Get the amount of cargo per economy-month that needs to be delivered (per TownEffect) for a
 	 *  town to grow. All goals need to be reached before a town will grow.
 	 * @param town_id The index of the town.
 	 * @param towneffect_id The index of the towneffect.
 	 * @pre IsValidTown(town_id).
 	 * @pre ScriptCargo::IsValidTownEffect(towneffect_id).
-	 * @return The goal of the cargo.
+	 * @return The goal of the cargo (amount per economy-month).
 	 * @note Goals can change over time. For example with a changing snowline, or
 	 *  with a growing town.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetCargoGoal(TownID town_id, ScriptCargo::TownEffect towneffect_id);
 
 	/**
-	 * Set the amount of days between town growth.
+	 * Set the amount of economy-days between town growth.
 	 * @param town_id The index of the town.
-	 * @param days_between_town_growth The amount of days between town growth, TOWN_GROWTH_NONE or TOWN_GROWTH_NORMAL.
+	 * @param days_between_town_growth The amount of economy-days between town growth, TOWN_GROWTH_NONE or TOWN_GROWTH_NORMAL.
 	 * @pre IsValidTown(town_id).
 	 * @pre days_between_town_growth <= 880 || days_between_town_growth == TOWN_GROWTH_NONE || days_between_town_growth == TOWN_GROWTH_NORMAL.
 	 * @return True if the action succeeded.
 	 * @note Even when setting a growth rate, towns only grow when the conditions for growth (SetCargoCoal) are met,
 	 *       and the game settings (economy.town_growth_rate) allow town growth at all.
 	 * @note When changing the growth rate, the relative progress is preserved and scaled to the new rate.
+	 * @see \ref ScriptEconomyTime
 	 * @api -ai
 	 */
 	static bool SetGrowthRate(TownID town_id, SQInteger days_between_town_growth);
 
 	/**
-	 * Get the amount of days between town growth.
+	 * Get the amount of economy-days between town growth.
 	 * @param town_id The index of the town.
 	 * @pre IsValidTown(town_id).
-	 * @return Amount of days between town growth, or TOWN_GROWTH_NONE.
+	 * @return Amount of economy-days between town growth, or TOWN_GROWTH_NONE.
 	 * @note This function does not indicate when it will grow next. It only tells you the time between growths.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetGrowthRate(TownID town_id);
 
@@ -332,8 +343,9 @@ public:
 	 * Find out how long the town is undergoing road reconstructions.
 	 * @param town_id The town to check.
 	 * @pre IsValidTown(town_id).
-	 * @return The number of months the road reworks are still going to take.
+	 * @return The number of economy-months the road reworks are still going to take.
 	 *         The value 0 means that there are currently no road reworks.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetRoadReworkDuration(TownID town_id);
 
@@ -341,8 +353,9 @@ public:
 	 * Find out how long new buildings are still being funded in a town.
 	 * @param town_id The town to check.
 	 * @pre IsValidTown(town_id).
-	 * @return The number of months building construction is still funded.
+	 * @return The number of economy-months building construction is still funded.
 	 *         The value 0 means that there is currently no funding.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetFundBuildingsDuration(TownID town_id);
 
@@ -361,9 +374,10 @@ public:
 	 * Find out how long the town is under influence of the exclusive rights.
 	 * @param town_id The town to check.
 	 * @pre IsValidTown(town_id).
-	 * @return The number of months the exclusive rights hold.
+	 * @return The number of economy-months the exclusive rights hold.
 	 *         The value 0 means that there are currently no exclusive rights
 	 *         given out to anyone.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static SQInteger GetExclusiveRightsDuration(TownID town_id);
 
diff --git a/src/script/api/script_vehicle.hpp b/src/script/api/script_vehicle.hpp
index d9c5309956..9344d65086 100644
--- a/src/script/api/script_vehicle.hpp
+++ b/src/script/api/script_vehicle.hpp
@@ -188,8 +188,8 @@ public:
 	 * Get the current age of a vehicle.
 	 * @param vehicle_id The vehicle to get the age of.
 	 * @pre IsValidVehicle(vehicle_id).
-	 * @return The current age the vehicle has.
-	 * @note The age is in days.
+	 * @return The current age of the vehicle in calendar-days.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static SQInteger GetAge(VehicleID vehicle_id);
 
@@ -199,8 +199,8 @@ public:
 	 * @param wagon The wagon in the vehicle to get the age of.
 	 * @pre IsValidVehicle(vehicle_id).
 	 * @pre wagon < GetNumWagons(vehicle_id).
-	 * @return The current age the vehicle has.
-	 * @note The age is in days.
+	 * @return The current age of the vehicle in calendar-days.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static SQInteger GetWagonAge(VehicleID vehicle_id, SQInteger wagon);
 
@@ -208,8 +208,8 @@ public:
 	 * Get the maximum age of a vehicle.
 	 * @param vehicle_id The vehicle to get the age of.
 	 * @pre IsPrimaryVehicle(vehicle_id).
-	 * @return The maximum age the vehicle has.
-	 * @note The age is in days.
+	 * @return The maximum age for the vehicle in calendar-days.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static SQInteger GetMaxAge(VehicleID vehicle_id);
 
@@ -217,8 +217,8 @@ public:
 	 * Get the age a vehicle has left (maximum - current).
 	 * @param vehicle_id The vehicle to get the age of.
 	 * @pre IsPrimaryVehicle(vehicle_id).
-	 * @return The age the vehicle has left.
-	 * @note The age is in days.
+	 * @return The remaining age of the vehicle in calendar-days.
+	 * @see \ref ScriptCalendarTime
 	 */
 	static SQInteger GetAgeLeft(VehicleID vehicle_id);
 
@@ -245,10 +245,10 @@ public:
 	 * Get the running cost of this vehicle.
 	 * @param vehicle_id The vehicle to get the running cost of.
 	 * @pre IsPrimaryVehicle(vehicle_id).
-	 * @return The running cost of the vehicle per year.
-	 * @note Cost is per year; divide by 365 to get per day.
+	 * @return The running cost of the vehicle per economy-year.
 	 * @note This is not equal to ScriptEngine::GetRunningCost for Trains, because
 	 *   wagons and second engines can add up in the calculation too.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetRunningCost(VehicleID vehicle_id);
 
@@ -256,7 +256,8 @@ public:
 	 * Get the current profit of a vehicle.
 	 * @param vehicle_id The vehicle to get the profit of.
 	 * @pre IsPrimaryVehicle(vehicle_id).
-	 * @return The current profit the vehicle has.
+	 * @return The profit the vehicle has made this economy-year so far.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetProfitThisYear(VehicleID vehicle_id);
 
@@ -264,7 +265,8 @@ public:
 	 * Get the profit of last year of a vehicle.
 	 * @param vehicle_id The vehicle to get the profit of.
 	 * @pre IsPrimaryVehicle(vehicle_id).
-	 * @return The profit the vehicle had last year.
+	 * @return The profit the vehicle made in the previous economy-year.
+	 * @see \ref ScriptEconomyTime
 	 */
 	static Money GetProfitLastYear(VehicleID vehicle_id);