time: update doc comments (#18947)

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')

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.

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

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

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

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

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)

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{}