hare

commit efe77dff6d8b88845b9e9fc5cd18451e4ca2ad14
parent e6d40f6da1fe80c50816825d20e546c8198296d9
Author: Byron Torres <b@torresjrjr.com>
Date:   Mon, 10 Jan 2022 10:41:34 +0000

update comments for localize(), lookupzone()

Signed-off-by: Byron Torres <b@torresjrjr.com>

Diffstat:
M
datetime/timezone.ha
 | 
10
+++++++---
M
time/chrono/timezone.ha
 | 
10
+++++++---

2 files changed, 14 insertions(+), 6 deletions(-)
diff --git a/datetime/timezone.ha b/datetime/timezone.ha
@@ -9,13 +9,17 @@ export fn in(loc: chrono::locality, dt: datetime) datetime = {
 	return new_dt;
 };
 
-// Returns a fictitious datetime which assumes it's own locality is the normal
-// locality. Its fields are adjusted by its current zone's offset.
+// Returns a fictitious [[datetime]] which is adjusted and normalized as if its
+// locality was the normal locality. Its fields are adjusted by its current
+// [[chrono::zone]]'s offset.
+//
+// This is a utility function for use by other modules's internal calculations.
+// You probably shouldn't use this directly.
 export fn localize(dt: datetime) datetime = {
 	return from_moment(chrono::localize(to_moment(dt)));
 };
 
-// Finds a [[datetime]]'s currently observed zone
+// Finds and returns a [[datetime]]'s currently observed zone
 export fn lookupzone(dt: *datetime) chrono::zone = {
 	const m = to_moment(*dt);
 	const z = chrono::lookupzone(&m);
diff --git a/time/chrono/timezone.ha b/time/chrono/timezone.ha
@@ -63,8 +63,12 @@ export fn in(loc: locality, m: moment) moment = {
 	return new(m.date, m.time, loc); // resets .zone
 };
 
-// Returns a fictitious moment which assumes it's own locality is the normal
-// locality. Its .date & .time fields are adjusted by its current zone's offset.
+// Returns a fictitious [[moment]] which is adjusted and normalized as if its
+// locality was the normal locality. Its fields are adjusted by its current
+// [[zone]]'s offset.
+//
+// This is a utility function for use by other modules's internal calculations.
+// You probably shouldn't use this directly.
 export fn localize(m: moment) moment = {
 	const zone = lookupzone(&m);
 	const daylen = m.loc.daylength;
@@ -80,7 +84,7 @@ export fn localize(m: moment) moment = {
 	return m;
 };
 
-// Finds a [[moment]]'s currently observed zone
+// Finds and returns a [[moment]]'s currently observed zone
 export fn lookupzone(m: *moment) zone = {
 	if (m.zone is zone) {
 		return m.zone as zone;