Fix actively-misleading comments about the contents of struct pg_tm.

pgtime.h documented the PG interpretation of tm_mon right alongside
the POSIX interpretation of tm_year, with no hint that neither
comment was correct throughout our code.

Perhaps someday we ought to switch to using two separate struct
definitions to provide a clearer indication of which semantics are
in use where.  But I fear the tedium-versus-safety-gain tradeoff
would not be very good.

Discussion: https://postgr.es/m/CAJ7c6TOMG8zSNEZtCn5SPe+cCk3Lfxb71ZaQwT2F4T7PJ_t=KA@mail.gmail.com

diff --git a/src/include/pgtime.h b/src/include/pgtime.h
index 28bd27e7f79f9eadea999b1f30f4035be9ef2203..92350527f65ec118a4cba1be5e305f0984ef27f1 100644 (file)
--- a/src/include/pgtime.h
+++ b/src/include/pgtime.h
@@ -22,14 +22,21 @@
 
 typedef int64 pg_time_t;
 
+/*
+ * CAUTION: the IANA timezone library (src/timezone/) follows the POSIX
+ * convention that tm_mon counts from 0 and tm_year is relative to 1900.
+ * However, Postgres' datetime functions generally treat tm_mon as counting
+ * from 1 and tm_year as relative to 1 BC.  Be sure to make the appropriate
+ * adjustments when moving from one code domain to the other.
+ */
 struct pg_tm
 {
    int         tm_sec;
    int         tm_min;
    int         tm_hour;
    int         tm_mday;
-   int         tm_mon;         /* origin 1, not 0! */
-   int         tm_year;        /* relative to 1900 */
+   int         tm_mon;         /* see above */
+   int         tm_year;        /* see above */
    int         tm_wday;
    int         tm_yday;
    int         tm_isdst;