From 70ad49e1867ad7337c5f29f12483eabc7db6a2ce Mon Sep 17 00:00:00 2001
From: crthpl <56052645+crthpl@users.noreply.github.com>
Date: Wed, 13 Jan 2021 06:30:54 -0800
Subject: [PATCH] time: complete doc (#8070)

---
 vlib/time/misc/misc.v      |  2 +-
 vlib/time/operator.v       |  2 +-
 vlib/time/stopwatch.v      |  7 ++++++-
 vlib/time/time.v           | 29 ++++++++++++++++++++++++-----
 vlib/time/time_linux.c.v   |  9 +++++----
 vlib/time/time_nix.c.v     |  1 +
 vlib/time/time_windows.c.v |  1 +
 7 files changed, 39 insertions(+), 12 deletions(-)

diff --git a/vlib/time/misc/misc.v b/vlib/time/misc/misc.v
index c18a8965d3..122659a7cc 100644
--- a/vlib/time/misc/misc.v
+++ b/vlib/time/misc/misc.v
@@ -4,7 +4,7 @@ import rand
 import time
 
 const (
-	start_time_unix = time.now().unix
+	start_time_unix = time.now().unix // start_time_unix is set when the program is started.
 )
 
 // random returns a random time struct in *the past*.
diff --git a/vlib/time/operator.v b/vlib/time/operator.v
index fff2c5590f..4de7d8de5b 100644
--- a/vlib/time/operator.v
+++ b/vlib/time/operator.v
@@ -45,7 +45,7 @@ pub fn (t1 Time) >= (t2 Time) bool {
 	return t1 > t2 || t1 == t2
 }
 
-// Time subtract using eperator overloading
+// Time subtract using operator overloading.
 [inline]
 pub fn (lhs Time) - (rhs Time) Duration {
 	lhs_micro := lhs.unix * 1000 * 1000 + u64(lhs.microsecond)
diff --git a/vlib/time/stopwatch.v b/vlib/time/stopwatch.v
index 49faedf524..406dd9ccb7 100644
--- a/vlib/time/stopwatch.v
+++ b/vlib/time/stopwatch.v
@@ -7,6 +7,7 @@ pub struct StopWatchOptions {
 	auto_start bool = true
 }
 
+// StopWatch is used to measure elapsed time.
 pub struct StopWatch {
 mut:
 	elapsed u64
@@ -15,6 +16,7 @@ pub mut:
 	end   u64
 }
 
+// new_stopwatch initializes a new StopWatch with the current time as start.
 pub fn new_stopwatch(opts StopWatchOptions) StopWatch {
 	mut initial := u64(0)
 	if opts.auto_start {
@@ -27,22 +29,25 @@ pub fn new_stopwatch(opts StopWatchOptions) StopWatch {
 	}
 }
 
-// start Starts the timer. If the timer was paused, restarts counting.
+// start starts the stopwatch. If the timer was paused, restarts 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.
 pub fn (mut t StopWatch) restart() {
 	t.start = sys_mono_now()
 	t.end = 0
 	t.elapsed = 0
 }
 
+// stop stops the timer, by setting the end time to the current time.
 pub fn (mut t StopWatch) stop() {
 	t.end = sys_mono_now()
 }
 
+// pause resets the `start` time and adds the current elapsed time to `elapsed`.
 pub fn (mut t StopWatch) pause() {
 	if t.start > 0 {
 		if t.end == 0 {
diff --git a/vlib/time/time.v b/vlib/time/time.v
index 56423469bf..dda5620867 100644
--- a/vlib/time/time.v
+++ b/vlib/time/time.v
@@ -37,6 +37,7 @@ const (
 	long_days          = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday']
 )
 
+// Time contains various time units for a point in time.
 pub struct Time {
 pub:
 	year        int
@@ -49,6 +50,7 @@ pub:
 	unix        u64
 }
 
+// FormatDelimiter contains different time formats.
 pub enum FormatTime {
 	hhmm12
 	hhmm24
@@ -59,6 +61,7 @@ pub enum FormatTime {
 	no_time
 }
 
+// FormatDelimiter contains different date formats.
 pub enum FormatDate {
 	ddmmyy
 	ddmmyyyy
@@ -71,6 +74,7 @@ pub enum FormatDate {
 	yyyymmdd
 }
 
+// FormatDelimiter contains different time/date delimiters.
 pub enum FormatDelimiter {
 	dot
 	hyphen
@@ -79,6 +83,7 @@ pub enum FormatDelimiter {
 	no_delimiter
 }
 
+// C.timeval represents a C time value.
 pub struct C.timeval {
 	tv_sec  u64
 	tv_usec u64
@@ -109,7 +114,7 @@ pub fn now() Time {
 	return convert_ctime(now, 0)
 }
 
-// utc returns the current time in utc
+// utc returns the current UTC time.
 pub fn utc() Time {
 	$if macos {
 		return darwin_utc()
@@ -195,8 +200,8 @@ fn since(t Time) int {
 	return 0
 }
 
-// relative returns a string representation of difference between time
-// and current time.
+// relative returns a string representation of the difference between t
+// and the current time.
 pub fn (t Time) relative() string {
 	znow := now()
 	secs := znow.unix - t.unix
@@ -235,6 +240,19 @@ pub fn (t Time) relative() string {
 	return t.md()
 }
 
+// relative_short returns a string saying how long ago a time occured as follows:
+// 0-30 seconds: `"now"`; 30-60 seconds: `"1m"`; anything else is rounded to the
+// nearest minute, hour or day; anything higher than 10000 days (about 27 years)
+// years returns an empty string.
+// Some Examples:
+// `0s -> 'now'`;
+// `20s -> 'now'`;
+// `47s -> '1m'`;
+// `456s -> '7m'`;
+// `1234s -> '20m'`;
+// `16834s -> '4h'`;
+// `1687440s -> '33d'`;
+// `15842354871s -> ''`
 pub fn (t Time) relative_short() string {
 	znow := now()
 	secs := znow.unix - t.unix
@@ -355,6 +373,7 @@ pub fn (t Time) str() string {
 	return t.format_ss()
 }
 
+// convert_ctime converts a C time to V time.
 fn convert_ctime(t C.tm, microsecond int) Time {
 	return Time{
 		year: t.tm_year + 1900
@@ -368,7 +387,7 @@ fn convert_ctime(t C.tm, microsecond int) Time {
 	}
 }
 
-// A lot of these are taken from the Go library
+// A lot of these are taken from the Go library.
 pub type Duration = i64
 
 pub const (
@@ -419,7 +438,7 @@ pub fn (d Duration) hours() f64 {
 	return f64(hr) + f64(nsec) / (60 * 60 * 1e9)
 }
 
-// offset returns time zone UTC offset in seconds
+// offset returns time zone UTC offset in seconds.
 pub fn offset() int {
 	t := now()
 	local := t.local()
diff --git a/vlib/time/time_linux.c.v b/vlib/time/time_linux.c.v
index 83a2f93994..b0ab7ad7ce 100644
--- a/vlib/time/time_linux.c.v
+++ b/vlib/time/time_linux.c.v
@@ -1,25 +1,26 @@
 module time
 
+// sys_mono_now_darwin - dummy fn to compile on all platforms/compilers
 fn sys_mono_now_darwin() u64 {
 	return 0
 }
 
-// dummy to compile with all compilers
+// darwin_now - dummy fn to compile on all platforms/compilers
 pub fn darwin_now() Time {
 	return Time{}
 }
 
-// dummy to compile with all compilers
+// solaris_now - dummy fn to compile on all platforms/compilers
 pub fn solaris_now() Time {
 	return Time{}
 }
 
-// dummy to compile with all compilers
+// darwin_utc - dummy fn to compile on all platforms/compilers
 pub fn darwin_utc() Time {
 	return Time{}
 }
 
-// dummy to compile with all compilers
+// solaris_utc - dummy fn to compile on all platforms/compilers
 pub fn solaris_utc() Time {
 	return Time{}
 }
diff --git a/vlib/time/time_nix.c.v b/vlib/time/time_nix.c.v
index 98a8e98f6d..aa6d209883 100644
--- a/vlib/time/time_nix.c.v
+++ b/vlib/time/time_nix.c.v
@@ -44,6 +44,7 @@ mut:
 // the first arg is defined in include/bits/types.h as `__S32_TYPE`, which is `int`
 fn C.clock_gettime(int, &C.timespec)
 
+// sys_mono_now returns a *monotonically increasing time*, NOT a time adjusted for daylight savings, location etc.
 pub fn sys_mono_now() u64 {
 	$if macos {
 		return sys_mono_now_darwin()
diff --git a/vlib/time/time_windows.c.v b/vlib/time/time_windows.c.v
index 6794314331..3a692da883 100644
--- a/vlib/time/time_windows.c.v
+++ b/vlib/time/time_windows.c.v
@@ -71,6 +71,7 @@ fn init_win_time_start() u64 {
 	return s
 }
 
+// sys_mono_now returns a *monotonically increasing time*, NOT a time adjusted for daylight savings, location etc.
 pub fn sys_mono_now() u64 {
 	tm := u64(0)
 	C.QueryPerformanceCounter(&tm) // XP or later never fail