From ac0ae1966ad3697e6d307e281e6902cb9fa1e753 Mon Sep 17 00:00:00 2001
From: Turiiya <34311583+tobealive@users.noreply.github.com>
Date: Sat, 22 Jul 2023 20:30:36 +0200
Subject: [PATCH] time: update doc comments (#18947)

---
 vlib/time/parse.c.v    | 6 +++---
 vlib/time/parse.js.v   | 2 +-
 vlib/time/stopwatch.v  | 4 ++--
 vlib/time/time.c.v     | 9 +++++----
 vlib/time/time.js.v    | 5 +++--
 vlib/time/time.v       | 8 ++++----
 vlib/time/time_js.js.v | 1 +
 vlib/time/time_nix.c.v | 4 ++--
 8 files changed, 21 insertions(+), 18 deletions(-)

diff --git a/vlib/time/parse.c.v b/vlib/time/parse.c.v
index 76bb3d3f4a..d4b7fe97df 100644
--- a/vlib/time/parse.c.v
+++ b/vlib/time/parse.c.v
@@ -5,7 +5,7 @@ module time
 
 import strconv
 
-// parse_rfc3339 returns time from a date string in RFC 3339 datetime format.
+// parse_rfc3339 returns the time from a date string in RFC 3339 datetime format.
 // See also https://ijmacd.github.io/rfc3339-iso8601/ for a visual reference of
 // the differences between ISO-8601 and RFC 3339.
 pub fn parse_rfc3339(s string) !Time {
@@ -59,7 +59,7 @@ pub fn parse_rfc3339(s string) !Time {
 	return error_invalid_time(9, 'malformed date')
 }
 
-// parse returns time from a date string in "YYYY-MM-DD HH:mm:ss" format.
+// parse returns the time from a date string in "YYYY-MM-DD HH:mm:ss" format.
 pub fn parse(s string) !Time {
 	if s == '' {
 		return error_invalid_time(0, 'datetime string is empty')
@@ -197,7 +197,7 @@ pub fn parse_iso8601(s string) !Time {
 	return t
 }
 
-// parse_rfc2822 returns time from a date string in RFC 2822 datetime format.
+// parse_rfc2822 returns the time from a date string in RFC 2822 datetime format.
 pub fn parse_rfc2822(s string) !Time {
 	if s == '' {
 		return error_invalid_time(0, 'datetime string is empty')
diff --git a/vlib/time/parse.js.v b/vlib/time/parse.js.v
index 93c80045e6..d53d232912 100644
--- a/vlib/time/parse.js.v
+++ b/vlib/time/parse.js.v
@@ -1,6 +1,6 @@
 module time
 
-// parse returns time from a date string.
+// parse returns the time from a date string.
 //
 // TODO(playX): JS Date expects iso8061 format of strings and other formats
 // are implementation dependent, we probably want to implement parsing in JS.
diff --git a/vlib/time/stopwatch.v b/vlib/time/stopwatch.v
index a51b9ef3c8..46fc4a3064 100644
--- a/vlib/time/stopwatch.v
+++ b/vlib/time/stopwatch.v
@@ -30,13 +30,13 @@ pub fn new_stopwatch(opts StopWatchOptions) StopWatch {
 	}
 }
 
-// start starts the stopwatch. If the timer was paused, restarts counting.
+// start starts the stopwatch. If the timer was paused, it continues counting.
 pub fn (mut t StopWatch) start() {
 	t.start = sys_mono_now()
 	t.end = 0
 }
 
-// restart restarts the stopwatch. If the timer was paused, restarts counting.
+// restart restarts the stopwatch. If the timer was paused, it restarts counting.
 pub fn (mut t StopWatch) restart() {
 	t.start = sys_mono_now()
 	t.end = 0
diff --git a/vlib/time/time.c.v b/vlib/time/time.c.v
index 2f09c2c54b..8e993dfa93 100644
--- a/vlib/time/time.c.v
+++ b/vlib/time/time.c.v
@@ -20,7 +20,7 @@ fn C.gmtime(t &C.time_t) &C.tm
 fn C.gmtime_r(t &C.time_t, res &C.tm) &C.tm
 fn C.strftime(buf &char, maxsize usize, const_format &char, const_tm &C.tm) usize
 
-// now returns current local time.
+// now returns the current local time.
 pub fn now() Time {
 	$if macos {
 		return darwin_now()
@@ -62,7 +62,7 @@ pub fn utc() Time {
 	*/
 }
 
-// new_time returns a time struct with calculated Unix time.
+// new_time returns a time struct with the calculated Unix time.
 pub fn new_time(t Time) Time {
 	if t.unix != 0 {
 		return t
@@ -82,7 +82,8 @@ pub fn new_time(t Time) Time {
 	}
 }
 
-// ticks returns a number of milliseconds elapsed since system start.
+// ticks returns the number of milliseconds since the UNIX epoch.
+// On Windows ticks returns the number of milliseconds elapsed since system start.
 pub fn ticks() i64 {
 	$if windows {
 		return C.GetTickCount()
@@ -96,7 +97,7 @@ pub fn ticks() i64 {
 	// # return (double)(* (uint64_t *) &elapsedNano) / 1000000;
 }
 
-// str returns time in the same format as `parse` expects ("YYYY-MM-DD HH:mm:ss").
+// str returns the time in the same format as `parse` expects ("YYYY-MM-DD HH:mm:ss").
 pub fn (t Time) str() string {
 	// TODO Define common default format for
 	// `str` and `parse` and use it in both ways
diff --git a/vlib/time/time.js.v b/vlib/time/time.js.v
index e04d25fae4..8c486d2fae 100644
--- a/vlib/time/time.js.v
+++ b/vlib/time/time.js.v
@@ -30,20 +30,21 @@ pub fn utc() Time {
 	return res
 }
 
-/// Returns local time
+// local returns the local time.
 pub fn (t Time) local() Time {
 	// TODO: Does this actually correct? JS clock is always set to timezone or no?
 	// if it is not we should try to use Intl for getting local time.
 	return t
 }
 
+// sleep suspends the execution for a given duration (in nanoseconds).
 pub fn sleep(dur Duration) {
 	#let now = new Date().getTime()
 	#let toWait = BigInt(dur.val) / BigInt(time__millisecond)
 	#while (new Date().getTime() < now + Number(toWait)) {}
 }
 
-// new_time returns a time struct with calculated Unix time.
+// new_time returns a time struct with the calculated Unix time.
 pub fn new_time(t Time) Time {
 	if t.unix != 0 {
 		return t
diff --git a/vlib/time/time.v b/vlib/time/time.v
index 3fe3206ac6..4407c08cc9 100644
--- a/vlib/time/time.v
+++ b/vlib/time/time.v
@@ -90,7 +90,7 @@ pub fn Time.new(t Time) Time {
 	return new_time(t)
 }
 
-// smonth returns month name abbreviation.
+// smonth returns the month name abbreviation.
 pub fn (t Time) smonth() string {
 	if t.month <= 0 || t.month > 12 {
 		return '---'
@@ -99,19 +99,19 @@ pub fn (t Time) smonth() string {
 	return time.months_string[i * 3..(i + 1) * 3]
 }
 
-// unix_time returns Unix time.
+// unix_time returns the UNIX time.
 [inline]
 pub fn (t Time) unix_time() i64 {
 	return t.unix
 }
 
-// unix_time_milli returns Unix time with millisecond resolution.
+// unix_time_milli returns the UNIX time with millisecond resolution.
 [inline]
 pub fn (t Time) unix_time_milli() i64 {
 	return t.unix * 1000 + (t.microsecond / 1000)
 }
 
-// add returns a new time that duration is added
+// add returns a new time with the given duration added.
 pub fn (t Time) add(d Duration) Time {
 	microseconds := i64(t.unix) * 1_000_000 + t.microsecond + d.microseconds()
 	unix := microseconds / 1_000_000
diff --git a/vlib/time/time_js.js.v b/vlib/time/time_js.js.v
index f09c474616..fe382ae915 100644
--- a/vlib/time/time_js.js.v
+++ b/vlib/time/time_js.js.v
@@ -11,6 +11,7 @@ module time
 #return t + $timeOff
 #}
 
+// sys_mono_now returns a *monotonically increasing time*, NOT a time adjusted for daylight savings, location etc.
 pub fn sys_mono_now() u64 {
 	$if js_browser {
 		mut res := u64(0)
diff --git a/vlib/time/time_nix.c.v b/vlib/time/time_nix.c.v
index 48cf9aa819..117493425f 100644
--- a/vlib/time/time_nix.c.v
+++ b/vlib/time/time_nix.c.v
@@ -125,7 +125,7 @@ pub fn (d Duration) timespec() C.timespec {
 	return ts
 }
 
-// return timespec of 1970/1/1
+// zero_timespec returns the calendar time in seconds and nanoseconds of the beginning of the Unix epoch.
 pub fn zero_timespec() C.timespec {
 	ts := C.timespec{
 		tv_sec: 0
@@ -134,7 +134,7 @@ pub fn zero_timespec() C.timespec {
 	return ts
 }
 
-// sleep makes the calling thread sleep for a given duration (in nanoseconds).
+// sleep suspends the execution of the calling thread for a given duration (in nanoseconds).
 pub fn sleep(duration Duration) {
 	mut req := C.timespec{duration / second, duration % second}
 	rem := C.timespec{}