api: Improve doc comments for v1.MinTime and v1.MaxTime (#14986)

api: Improve doc comments for v1.MinTime and v1.MaxTime

While investigated something mostly unrelated, I got nerd-sniped by
the calculation of v1.MinTime and v1.MaxTime. The seemingly magic
number in there (62135596801) needed an explanation. While looking for
it, I found out that the offsets used here are actually needlessly
conservative. Since the timestamps are so far in the past or future,
respectively, that there is no practical impact, except that the
calculation is needlessly obfuscated. However, we won't change the
values now to not cause any confusion for users of this code. Still, I
think the doc comment should explain the circumstances so nobody gets
nerd-sniped again as I did today.

For the record: 62135596800 is the difference in seconds between 0001-01-01 00:00:00 (Unix time zero point) and 1971-01-01 00:00:00 (Go time zero point) in the Gregorian calendar. If "Prometheus time" were in seconds (not milliseconds), that difference would be relevant to prevent over-/underflow when converting from "Prometheus time" to "Go time".

Signed-off-by: beorn7 <beorn@grafana.com>

---------

Signed-off-by: beorn7 <beorn@grafana.com>

web/api/v1/api.go

@@ -834,12 +834,22 @@ func (api *API) labelValues(r *http.Request) (result apiFuncResult) {
 }
 
 var (
-	// MinTime is the default timestamp used for the begin of optional time ranges.
+	// MinTime is the default timestamp used for the start of optional time ranges.
-	// Exposed to let downstream projects to reference it.
+	// Exposed to let downstream projects reference it.
+	//
+	// Historical note: This should just be time.Unix(math.MinInt64/1000, 0).UTC(),
+	// but it was set to a higher value in the past due to a misunderstanding.
+	// The value is still low enough for practical purposes, so we don't want
+	// to change it now, avoiding confusion for importers of this variable.
 	MinTime = time.Unix(math.MinInt64/1000+62135596801, 0).UTC()
 
 	// MaxTime is the default timestamp used for the end of optional time ranges.
 	// Exposed to let downstream projects to reference it.
+	//
+	// Historical note: This should just be time.Unix(math.MaxInt64/1000, 0).UTC(),
+	// but it was set to a lower value in the past due to a misunderstanding.
+	// The value is still high enough for practical purposes, so we don't want
+	// to change it now, avoiding confusion for importers of this variable.
 	MaxTime = time.Unix(math.MaxInt64/1000-62135596801, 999999999).UTC()
 
 	minTimeFormatted = MinTime.Format(time.RFC3339Nano)