document time

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

diff --git a/src/lib/time/sleep.go b/src/lib/time/sleep.go
index 1ce58b291f53a132adcac4a9b6456e5913a3f712..8451c6d80171e850fcebb9129abe6debdf984250 100644 (file)
--- 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 cb76b7cd4ae66eebf39733900c9bc668676da5c5..53e2234f89c80fa243ba9deefc465b0c9acd06ee 100644 (file)
--- 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 665b1c5ca48e05c49fc28c4e846594979aefc4eb..ea9b66cbc7a012fab5ae6bc471dd1df56e4861a0 100644 (file)
--- 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 577434c915f59e533e04898e30a96c222a53f2f4..62f86499e5d4573ce0de37d0d832948ca6672032 100644 (file)
--- 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