godoc: clarifies UTC on clock sources (#1300)

This makes clock source configuration more clear about the timestamps
returned. Specifically, that realtime is UTC and the most common
consumers.

Signed-off-by: Adrian Cole <adrian@tetrate.io>

config.go

@@ -509,8 +509,9 @@ type ModuleConfig interface {
 	WithStdout(io.Writer) ModuleConfig
 
 	// WithWalltime configures the wall clock, sometimes referred to as the
-	// real time clock. Defaults to a fake result that increases by 1ms on
-	// each reading.
+	// real time clock. sys.Walltime returns the current unix/epoch time,
+	// seconds since midnight UTC 1 January 1970, with a nanosecond fraction.
+	// This defaults to a fake result that increases by 1ms on each reading.
 	//
 	// Here's an example that uses a custom clock:
 	//	moduleConfig = moduleConfig.
@@ -518,8 +519,11 @@ type ModuleConfig interface {
 	//			return clock.walltime()
 	//		}, sys.ClockResolution(time.Microsecond.Nanoseconds()))
 	//
-	// Note: This does not default to time.Now as that violates sandboxing. Use
-	// WithSysWalltime for a usable implementation.
+	// # Notes:
+	//   - This does not default to time.Now as that violates sandboxing.
+	//   - This is used to implement host functions such as WASI
+	//     `clock_time_get` with the `realtime` clock ID.
+	//   - Use WithSysWalltime for a usable implementation.
 	WithWalltime(sys.Walltime, sys.ClockResolution) ModuleConfig
 
 	// WithSysWalltime uses time.Now for sys.Walltime with a resolution of 1us
@@ -540,6 +544,8 @@ type ModuleConfig interface {
 	//
 	// # Notes:
 	//   - This does not default to time.Since as that violates sandboxing.
+	//   - This is used to implement host functions such as WASI
+	//     `clock_time_get` with the `monotonic` clock ID.
 	//   - Some compilers implement sleep by looping on sys.Nanotime (e.g. Go).
 	//   - If you set this, you should probably set WithNanosleep also.
 	//   - Use WithSysNanotime for a usable implementation.
@@ -563,8 +569,8 @@ type ModuleConfig interface {
 	//			--snip--
 	//
 	// # Notes:
-	//   - This primarily supports `poll_oneoff` for relative clock events.
 	//   - This does not default to time.Sleep as that violates sandboxing.
+	//   - This is used to implement host functions such as WASI `poll_oneoff`.
 	//   - Some compilers implement sleep by looping on sys.Nanotime (e.g. Go).
 	//   - If you set this, you should probably set WithNanotime also.
 	//   - Use WithSysNanosleep for a usable implementation.

sys/clock.go

@@ -8,7 +8,8 @@ package sys
 // windows monotonic resolution can be 15ms. See /RATIONALE.md.
 type ClockResolution uint32
 
-// Walltime returns the current time in epoch seconds with a nanosecond fraction.
+// Walltime returns the current unix/epoch time, seconds since midnight UTC
+// 1 January 1970, with a nanosecond fraction.
 type Walltime func() (sec int64, nsec int32)
 
 // Nanotime returns nanoseconds since an arbitrary start point, used to measure