document time

R=rsc
DELTA=42  (23 added, 1 deleted, 18 changed)
OCL=25881
CL=25886

4 files changed, 41 insertions, 19 deletions

diff --git a/src/lib/time/sleep.go b/src/lib/time/sleep.go
index 1ce58b291..8451c6d80 100644
--- a/src/lib/time/sleep.go
+++ b/src/lib/time/sleep.go
@@ -10,6 +10,8 @@ import (
 	"unsafe";
 )
 
+// Sleep pauses the current goroutine for ns nanoseconds.
+// It returns os.EINTR if interrupted.
 func Sleep(ns int64) *os.Error {
 	var tv syscall.Timeval;
 	syscall.Nstotimeval(ns, &tv);
diff --git a/src/lib/time/tick.go b/src/lib/time/tick.go
index cb76b7cd4..53e2234f8 100644
--- a/src/lib/time/tick.go
+++ b/src/lib/time/tick.go
@@ -48,6 +48,9 @@ func ticker(ns int64, c chan int64) {
 	}
 }
 
+// Tick creates a synchronous channel that will send the time, in nanoseconds,
+// every ns nanoseconds.  It adjusts the intervals to make up for pauses in
+// delivery of the ticks.
 func Tick(ns int64) chan int64 {
 	if ns <= 0 {
 		return nil
diff --git a/src/lib/time/time.go b/src/lib/time/time.go
index 665b1c5ca..ea9b66cbc 100644
--- a/src/lib/time/time.go
+++ b/src/lib/time/time.go
@@ -2,6 +2,8 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// The time package provides functionality for measuring and
+// displaying time.
 package time
 
 import (
@@ -9,7 +11,8 @@ import (
 	"time"
 )
 
-// Seconds since January 1, 1970 00:00:00 UTC
+// Seconds reports the number of seconds since the Unix epoch,
+// January 1, 1970 00:00:00 UTC.
 func Seconds() int64 {
 	sec, nsec, err := os.Time();
 	if err != nil {
@@ -18,7 +21,8 @@ func Seconds() int64 {
 	return sec
 }
 
-// Nanoseconds since January 1, 1970 00:00:00 UTC
+// Nanoseconds reports the number of nanoseconds since the Unix epoch,
+// January 1, 1970 00:00:00 UTC.
 func Nanoseconds() int64 {
 	sec, nsec, err := os.Time();
 	if err != nil {
@@ -27,6 +31,7 @@ func Nanoseconds() int64 {
 	return sec*1e9 + nsec
 }
 
+// Days of the week.
 const (
 	Sunday = iota;
 	Monday;
@@ -37,11 +42,12 @@ const (
 	Saturday;
 )
 
+// Time is the struct representing a parsed time value.
 type Time struct {
 	Year int64;	// 2008 is 2008
 	Month, Day int;	// Sep-17 is 9, 17
 	Hour, Minute, Second int;	// 10:43:12 is 10, 43, 12
-	Weekday int;		// Sunday = 0, Monday = 1, ...
+	Weekday int;		// Sunday, Monday, ...
 	ZoneOffset int;	// seconds west of UTC
 	Zone string;
 }
@@ -70,6 +76,8 @@ const (
 	days1970To2001 = 31*365+8;
 )
 
+// SecondsToUTC converts sec, in number of seconds since the Unix epoch,
+// into a parsed Time value in the UTC time zone.
 func SecondsToUTC(sec int64) *Time {
 	t := new(Time);
 
@@ -143,12 +151,15 @@ func SecondsToUTC(sec int64) *Time {
 	return t;
 }
 
+// UTC returns the current time as a parsed Time value in the UTC time zone.
 func UTC() *Time {
 	return SecondsToUTC(Seconds())
 }
 
+// SecondsToLocalTime converts sec, in number of seconds since the Unix epoch,
+// into a parsed Time value in the local time zone.
 func SecondsToLocalTime(sec int64) *Time {
-	z, offset, err := time.LookupTimezone(sec);
+	z, offset, err := time.lookupTimezone(sec);
 	if err != nil {
 		return SecondsToUTC(sec)
 	}
@@ -158,11 +169,13 @@ func SecondsToLocalTime(sec int64) *Time {
 	return t
 }
 
+// LocalTime returns the current time as a parsed Time value in the local time zone.
 func LocalTime() *Time {
 	return SecondsToLocalTime(Seconds())
 }
 
-// Compute number of seconds since January 1, 1970.
+// Seconds returns the number of seconds since January 1, 1970 represented by the
+// parsed Time value.
 func (t *Time) Seconds() int64 {
 	// First, accumulate days since January 1, 2001.
 	// Using 2001 instead of 1970 makes the leap-year
@@ -334,23 +347,26 @@ func format(t *Time, fmt string) string {
 	return string(buf[0:bp])
 }
 
+// Asctime formats the parsed time value in the style of
 // ANSI C asctime: Sun Nov  6 08:49:37 1994
 func (t *Time) Asctime() string {
 	return format(t, "%a %b %e %H:%M:%S %Y")
 }
 
+// RFC850 formats the parsed time value in the style of
 // RFC 850: Sunday, 06-Nov-94 08:49:37 UTC
 func (t *Time) RFC850() string {
 	return format(t, "%A, %d-%b-%y %H:%M:%S %Z")
 }
 
+// RFC1123 formats the parsed time value in the style of
 // RFC 1123: Sun, 06 Nov 1994 08:49:37 UTC
 func (t *Time) RFC1123() string {
 	return format(t, "%a, %d %b %Y %H:%M:%S %Z")
 }
 
+// String formats the parsed time value in the style of
 // date(1) - Sun Nov  6 08:49:37 UTC 1994
 func (t *Time) String() string {
 	return format(t, "%a %b %e %H:%M:%S %Z %Y")
 }
-
diff --git a/src/lib/time/zoneinfo.go b/src/lib/time/zoneinfo.go
index 577434c91..62f86499e 100644
--- a/src/lib/time/zoneinfo.go
+++ b/src/lib/time/zoneinfo.go
@@ -22,9 +22,10 @@ const (
 	zoneDir = "/usr/share/zoneinfo/";
 )
 
+// Errors that can be generated recovering time zone information.
 var (
-	BadZoneinfo = os.NewError("time: malformed zoneinfo");
-	NoZoneinfo = os.NewError("time: unknown time zone")
+	badZoneinfo = os.NewError("time: malformed zoneinfo");
+	noZoneinfo = os.NewError("time: unknown time zone")
 )
 
 // Simple I/O interface to binary blob of data.
@@ -92,13 +93,13 @@ func parseinfo(bytes []byte) (zt []zonetime, err *os.Error) {
 
 	// 4-byte magic "TZif"
 	if magic := d.read(4); string(magic) != "TZif" {
-		return nil, BadZoneinfo
+		return nil, badZoneinfo
 	}
 
 	// 1-byte version, then 15 bytes of padding
 	var p []byte;
 	if p = d.read(16); len(p) != 16 || p[0] != 0 && p[0] != '2' {
-		return nil, BadZoneinfo
+		return nil, badZoneinfo
 	}
 	vers := p[0];
 
@@ -121,7 +122,7 @@ func parseinfo(bytes []byte) (zt []zonetime, err *os.Error) {
 	for i := 0; i < 6; i++ {
 		nn, ok := d.big4();
 		if !ok {
-			return nil, BadZoneinfo
+			return nil, badZoneinfo
 		}
 		n[i] = int(nn);
 	}
@@ -150,7 +151,7 @@ func parseinfo(bytes []byte) (zt []zonetime, err *os.Error) {
 	isutc := d.read(n[NUTCLocal]);
 
 	if d.error {	// ran out of data
-		return nil, BadZoneinfo
+		return nil, badZoneinfo
 	}
 
 	// If version == 2, the entire file repeats, this time using
@@ -165,16 +166,16 @@ func parseinfo(bytes []byte) (zt []zonetime, err *os.Error) {
 		var ok bool;
 		var n uint32;
 		if n, ok = zonedata.big4(); !ok {
-			return nil, BadZoneinfo
+			return nil, badZoneinfo
 		}
 		z[i].utcoff = int(n);
 		var b byte;
 		if b, ok = zonedata.byte(); !ok {
-			return nil, BadZoneinfo
+			return nil, badZoneinfo
 		}
 		z[i].isdst = b != 0;
 		if b, ok = zonedata.byte(); !ok || int(b) >= len(abbrev) {
-			return nil, BadZoneinfo
+			return nil, badZoneinfo
 		}
 		z[i].name = byteString(abbrev[b:len(abbrev)])
 	}
@@ -185,11 +186,11 @@ func parseinfo(bytes []byte) (zt []zonetime, err *os.Error) {
 		var ok bool;
 		var n uint32;
 		if n, ok = txtimes.big4(); !ok {
-			return nil, BadZoneinfo
+			return nil, badZoneinfo
 		}
 		zt[i].time = int32(n);
 		if int(txzones[i]) >= len(z) {
-			return nil, BadZoneinfo
+			return nil, badZoneinfo
 		}
 		zt[i].zone = &z[txzones[i]];
 		if i < len(isstd) {
@@ -211,7 +212,7 @@ func readfile(name string, max int) (p []byte, err *os.Error) {
 	n, err1 := io.Readn(fd, p);
 	fd.Close();
 	if err1 == nil {	// too long
-		return nil, BadZoneinfo;
+		return nil, badZoneinfo;
 	}
 	if err1 != io.ErrEOF {
 		return nil, err1;
@@ -251,7 +252,7 @@ func setupZone() {
 	}
 }
 
-func LookupTimezone(sec int64) (zone string, offset int, err *os.Error) {
+func lookupTimezone(sec int64) (zone string, offset int, err *os.Error) {
 	once.Do(setupZone);
 	if zoneerr != nil || len(zones) == 0 {
 		return "UTC", 0, zoneerr