time: add available godoc link

Change-Id: Idfe9cf2f2e4750d6673455f98deef2efc2d292a6
Reviewed-on: https://go-review.googlesource.com/c/go/+/539837
Reviewed-by: Ian Lance Taylor <iant@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Ian Lance Taylor <iant@golang.org>

src/time/format.go

@@ -6,13 +6,13 @@ package time
 
 import "errors"
 
-// These are predefined layouts for use in Time.Format and time.Parse.
+// These are predefined layouts for use in [Time.Format] and [time.Parse].
 // The reference time used in these layouts is the specific time stamp:
 //
 //	01/02 03:04:05PM '06 -0700
 //
 // (January 2, 15:04:05, 2006, in time zone seven hours west of GMT).
-// That value is recorded as the constant named Layout, listed below. As a Unix
+// That value is recorded as the constant named [Layout], listed below. As a Unix
 // time, this is 1136239445. Since MST is GMT-0700, the reference would be
 // printed by the Unix date command as:
 //
@@ -24,16 +24,16 @@ import "errors"
 // The example for Time.Format demonstrates the working of the layout string
 // in detail and is a good reference.
 //
-// Note that the RFC822, RFC850, and RFC1123 formats should be applied
+// Note that the [RFC822], [RFC850], and [RFC1123] formats should be applied
 // only to local times. Applying them to UTC times will use "UTC" as the
 // time zone abbreviation, while strictly speaking those RFCs require the
 // use of "GMT" in that case.
-// In general RFC1123Z should be used instead of RFC1123 for servers
-// that insist on that format, and RFC3339 should be preferred for new protocols.
-// RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting;
+// In general [RFC1123Z] should be used instead of [RFC1123] for servers
+// that insist on that format, and [RFC3339] should be preferred for new protocols.
+// [RFC3339], [RFC822], [RFC822Z], [RFC1123], and [RFC1123Z] are useful for formatting;
 // when used with time.Parse they do not accept all the time formats
 // permitted by the RFCs and they do accept time formats not formally defined.
-// The RFC3339Nano format removes trailing zeros from the seconds field
+// The [RFC3339Nano] format removes trailing zeros from the seconds field
 // and thus may not sort correctly once formatted.
 //
 // Most programs can use one of the defined constants as the layout passed to
@@ -41,8 +41,8 @@ import "errors"
 // creating a custom layout string.
 //
 // To define your own format, write down what the reference time would look like
-// formatted your way; see the values of constants like ANSIC, StampMicro or
-// Kitchen for examples. The model is to demonstrate what the reference time
+// formatted your way; see the values of constants like [ANSIC], [StampMicro] or
+// [Kitchen] for examples. The model is to demonstrate what the reference time
 // looks like so that the Format and Parse methods can apply the same
 // transformation to a general time value.
 //
@@ -553,7 +553,7 @@ func (t Time) String() string {
 	return s
 }
 
-// GoString implements fmt.GoStringer and formats t to be printed in Go source
+// GoString implements [fmt.GoStringer] and formats t to be printed in Go source
 // code.
 func (t Time) GoString() string {
 	abs := t.abs()
@@ -613,9 +613,9 @@ func (t Time) GoString() string {
 
 // Format returns a textual representation of the time value formatted according
 // to the layout defined by the argument. See the documentation for the
-// constant called Layout to see how to represent the layout format.
+// constant called [Layout] to see how to represent the layout format.
 //
-// The executable example for Time.Format demonstrates the working
+// The executable example for [Time.Format] demonstrates the working
 // of the layout string in detail and is a good reference.
 func (t Time) Format(layout string) string {
 	const bufSize = 64
@@ -631,7 +631,7 @@ func (t Time) Format(layout string) string {
 	return string(b)
 }
 
-// AppendFormat is like Format but appends the textual
+// AppendFormat is like [Time.Format] but appends the textual
 // representation to b and returns the extended buffer.
 func (t Time) AppendFormat(b []byte, layout string) []byte {
 	// Optimize for RFC3339 as it accounts for over half of all representations.
@@ -963,11 +963,11 @@ func skip(value, prefix string) (string, error) {
 }
 
 // Parse parses a formatted string and returns the time value it represents.
-// See the documentation for the constant called Layout to see how to
+// See the documentation for the constant called [Layout] to see how to
 // represent the format. The second argument must be parseable using
 // the format string (layout) provided as the first argument.
 //
-// The example for Time.Format demonstrates the working of the layout string
+// The example for [Time.Format] demonstrates the working of the layout string
 // in detail and is a good reference.
 //
 // When parsing (only), the input may contain a fractional second
@@ -991,7 +991,7 @@ func skip(value, prefix string) (string, error) {
 // In the absence of a time zone indicator, Parse returns a time in UTC.
 //
 // When parsing a time with a zone offset like -0700, if the offset corresponds
-// to a time zone used by the current location (Local), then Parse uses that
+// to a time zone used by the current location ([Local]), then Parse uses that
 // location and zone in the returned time. Otherwise it records the time as
 // being in a fabricated location with time fixed at the given zone offset.
 //
@@ -1003,7 +1003,7 @@ func skip(value, prefix string) (string, error) {
 // This choice means that such a time can be parsed and reformatted with the
 // same layout losslessly, but the exact instant used in the representation will
 // differ by the actual zone offset. To avoid such problems, prefer time layouts
-// that use a numeric zone offset, or use ParseInLocation.
+// that use a numeric zone offset, or use [ParseInLocation].
 func Parse(layout, value string) (Time, error) {
 	// Optimize for RFC3339 as it accounts for over half of all representations.
 	if layout == RFC3339 || layout == RFC3339Nano {

src/time/sleep.go

@@ -83,18 +83,18 @@ func resetTimer(t *Timer, when, period int64) bool
 
 // The Timer type represents a single event.
 // When the Timer expires, the current time will be sent on C,
-// unless the Timer was created by AfterFunc.
-// A Timer must be created with NewTimer or AfterFunc.
+// unless the Timer was created by [AfterFunc].
+// A Timer must be created with [NewTimer] or AfterFunc.
 type Timer struct {
 	C         <-chan Time
 	initTimer bool
 }
 
-// Stop prevents the Timer from firing.
+// Stop prevents the [Timer] from firing.
 // It returns true if the call stops the timer, false if the timer has already
 // expired or been stopped.
 //
-// For a func-based timer created with AfterFunc(d, f),
+// For a func-based timer created with [AfterFunc](d, f),
 // if t.Stop returns false, then the timer has already expired
 // and the function f has been started in its own goroutine;
 // Stop does not wait for f to complete before returning.
@@ -150,7 +150,7 @@ func NewTimer(d Duration) *Timer {
 // It returns true if the timer had been active, false if the timer had
 // expired or been stopped.
 //
-// For a func-based timer created with AfterFunc(d, f), Reset either reschedules
+// For a func-based timer created with [AfterFunc](d, f), Reset either reschedules
 // when f will run, in which case Reset returns true, or schedules f
 // to run again, in which case it returns false.
 // When Reset returns false, Reset neither waits for the prior f to
@@ -164,7 +164,7 @@ func NewTimer(d Duration) *Timer {
 // to receive a time value corresponding to the previous timer settings;
 // if the program has not received from t.C already and the timer is
 // running, Reset is guaranteed to return true.
-// Before Go 1.23, the only safe way to use Reset was to Stop and
+// Before Go 1.23, the only safe way to use Reset was to [Stop] and
 // explicitly drain the timer first.
 // See the [NewTimer] documentation for more details.
 func (t *Timer) Reset(d Duration) bool {
@@ -190,12 +190,12 @@ func sendTime(c any, seq uintptr, delta int64) {
 
 // After waits for the duration to elapse and then sends the current time
 // on the returned channel.
-// It is equivalent to NewTimer(d).C.
+// It is equivalent to [NewTimer](d).C.
 //
 // Before Go 1.23, this documentation warned that the underlying
-// Timer would not be recovered by the garbage collector until the
+// [Timer] would not be recovered by the garbage collector until the
 // timer fired, and that if efficiency was a concern, code should use
-// NewTimer instead and call Timer.Stop if the timer is no longer needed.
+// NewTimer instead and call [Timer.Stop] if the timer is no longer needed.
 // As of Go 1.23, the garbage collector can recover unreferenced,
 // unstopped timers. There is no reason to prefer NewTimer when After will do.
 func After(d Duration) <-chan Time {
@@ -203,7 +203,7 @@ func After(d Duration) <-chan Time {
 }
 
 // AfterFunc waits for the duration to elapse and then calls f
-// in its own goroutine. It returns a Timer that can
+// in its own goroutine. It returns a [Timer] that can
 // be used to cancel the call using its Stop method.
 // The returned Timer's C field is not used and will be nil.
 func AfterFunc(d Duration, f func()) *Timer {

src/time/tick.go

@@ -18,7 +18,7 @@ type Ticker struct {
 	initTicker bool
 }
 
-// NewTicker returns a new Ticker containing a channel that will send
+// NewTicker returns a new [Ticker] containing a channel that will send
 // the current time on the channel after each tick. The period of the
 // ticks is specified by the duration argument. The ticker will adjust
 // the time interval or drop ticks to make up for slow receivers.
@@ -72,13 +72,13 @@ func (t *Ticker) Reset(d Duration) {
 	resetTimer((*Timer)(unsafe.Pointer(t)), when(d), int64(d))
 }
 
-// Tick is a convenience wrapper for NewTicker providing access to the ticking
+// Tick is a convenience wrapper for [NewTicker] providing access to the ticking
 // channel only. Unlike NewTicker, Tick will return nil if d <= 0.
 //
 // Before Go 1.23, this documentation warned that the underlying
-// Ticker would never be recovered by the garbage collector, and that
+// [Ticker] would never be recovered by the garbage collector, and that
 // if efficiency was a concern, code should use NewTicker instead and
-// call Ticker.Stop when the ticker is no longer needed.
+// call [Ticker.Stop] when the ticker is no longer needed.
 // As of Go 1.23, the garbage collector can recover unreferenced
 // tickers, even if they haven't been stopped.
 // The Stop method is no longer necessary to help the garbage collector.

src/time/time.go

@@ -13,7 +13,7 @@
 // changes for clock synchronization, and a “monotonic clock,” which is
 // not. The general rule is that the wall clock is for telling time and
 // the monotonic clock is for measuring time. Rather than split the API,
-// in this package the Time returned by time.Now contains both a wall
+// in this package the Time returned by [time.Now] contains both a wall
 // clock reading and a monotonic clock reading; later time-telling
 // operations use the wall clock reading, but later time-measuring
 // operations, specifically comparisons and subtractions, use the
@@ -28,7 +28,7 @@
 //	t := time.Now()
 //	elapsed := t.Sub(start)
 //
-// Other idioms, such as time.Since(start), time.Until(deadline), and
+// Other idioms, such as [time.Since](start), [time.Until](deadline), and
 // time.Now().Before(deadline), are similarly robust against wall clock
 // resets.
 //
@@ -59,17 +59,17 @@
 // the current process, the serialized forms generated by t.GobEncode,
 // t.MarshalBinary, t.MarshalJSON, and t.MarshalText omit the monotonic
 // clock reading, and t.Format provides no format for it. Similarly, the
-// constructors time.Date, time.Parse, time.ParseInLocation, and time.Unix,
+// constructors [time.Date], [time.Parse], [time.ParseInLocation], and [time.Unix],
 // as well as the unmarshalers t.GobDecode, t.UnmarshalBinary.
 // t.UnmarshalJSON, and t.UnmarshalText always create times with
 // no monotonic clock reading.
 //
-// The monotonic clock reading exists only in Time values. It is not
-// a part of Duration values or the Unix times returned by t.Unix and
+// The monotonic clock reading exists only in [Time] values. It is not
+// a part of [Duration] values or the Unix times returned by t.Unix and
 // friends.
 //
 // Note that the Go == operator compares not just the time instant but
-// also the Location and the monotonic clock reading. See the
+// also the [Location] and the monotonic clock reading. See the
 // documentation for the Time type for a discussion of equality
 // testing for Time values.
 //
@@ -79,7 +79,7 @@
 //
 // # Timer Resolution
 //
-// Timer resolution varies depending on the Go runtime, the operating system
+// [Timer] resolution varies depending on the Go runtime, the operating system
 // and the underlying hardware.
 // On Unix, the resolution is ~1ms.
 // On Windows version 1803 and newer, the resolution is ~0.5ms.
@@ -96,27 +96,27 @@ import (
 //
 // Programs using times should typically store and pass them as values,
 // not pointers. That is, time variables and struct fields should be of
-// type time.Time, not *time.Time.
+// type [time.Time], not *time.Time.
 //
 // A Time value can be used by multiple goroutines simultaneously except
-// that the methods GobDecode, UnmarshalBinary, UnmarshalJSON and
-// UnmarshalText are not concurrency-safe.
+// that the methods [Time.GobDecode], [Time.UnmarshalBinary], [Time.UnmarshalJSON] and
+// [Time.UnmarshalText] are not concurrency-safe.
 //
-// Time instants can be compared using the Before, After, and Equal methods.
-// The Sub method subtracts two instants, producing a Duration.
-// The Add method adds a Time and a Duration, producing a Time.
+// Time instants can be compared using the [Time.Before], [Time.After], and [Time.Equal] methods.
+// The [Time.Sub] method subtracts two instants, producing a [Duration].
+// The [Time.Add] method adds a Time and a Duration, producing a Time.
 //
 // The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC.
-// As this time is unlikely to come up in practice, the IsZero method gives
+// As this time is unlikely to come up in practice, the [Time.IsZero] method gives
 // a simple way of detecting a time that has not been initialized explicitly.
 //
-// Each time has an associated Location. The methods Local, UTC, and In return a
+// Each time has an associated [Location]. The methods [Time.Local], [Time.UTC], and Time.In return a
 // Time with a specific Location. Changing the Location of a Time value with
 // these methods does not change the actual instant it represents, only the time
 // zone in which to interpret it.
 //
-// Representations of a Time value saved by the GobEncode, MarshalBinary,
-// MarshalJSON, and MarshalText methods store the Time.Location's offset, but not
+// Representations of a Time value saved by the [Time.GobEncode], [Time.MarshalBinary],
+// [Time.MarshalJSON], and [Time.MarshalText] methods store the [Time.Location]'s offset, but not
 // the location name. They therefore lose information about Daylight Saving Time.
 //
 // In addition to the required “wall clock” reading, a Time may contain an optional
@@ -626,7 +626,7 @@ const (
 // Common durations. There is no definition for units of Day or larger
 // to avoid confusion across daylight savings time zone transitions.
 //
-// To count the number of units in a Duration, divide:
+// To count the number of units in a [Duration], divide:
 //
 //	second := time.Second
 //	fmt.Print(int64(second/time.Millisecond)) // prints 1000
@@ -829,7 +829,7 @@ func lessThanHalf(x, y Duration) bool {
 // Round returns the result of rounding d to the nearest multiple of m.
 // The rounding behavior for halfway values is to round away from zero.
 // If the result exceeds the maximum (or minimum)
-// value that can be stored in a Duration,
+// value that can be stored in a [Duration],
 // Round returns the maximum (or minimum) duration.
 // If m <= 0, Round returns d unchanged.
 func (d Duration) Round(m Duration) Duration {
@@ -857,7 +857,7 @@ func (d Duration) Round(m Duration) Duration {
 }
 
 // Abs returns the absolute value of d.
-// As a special case, math.MinInt64 is converted to math.MaxInt64.
+// As a special case, [math.MinInt64] is converted to [math.MaxInt64].
 func (d Duration) Abs() Duration {
 	switch {
 	case d >= 0:
@@ -895,7 +895,7 @@ func (t Time) Add(d Duration) Time {
 }
 
 // Sub returns the duration t-u. If the result exceeds the maximum (or minimum)
-// value that can be stored in a Duration, the maximum (or minimum) duration
+// value that can be stored in a [Duration], the maximum (or minimum) duration
 // will be returned.
 // To compute t-d for a duration d, use t.Add(-d).
 func (t Time) Sub(u Time) Duration {
@@ -1358,7 +1358,7 @@ func (t *Time) GobDecode(data []byte) error {
 	return t.UnmarshalBinary(data)
 }
 
-// MarshalJSON implements the json.Marshaler interface.
+// MarshalJSON implements the [json.Marshaler] interface.
 // The time is a quoted string in the RFC 3339 format with sub-second precision.
 // If the timestamp cannot be represented as valid RFC 3339
 // (e.g., the year is out of range), then an error is reported.
@@ -1373,7 +1373,7 @@ func (t Time) MarshalJSON() ([]byte, error) {
 	return b, nil
 }
 
-// UnmarshalJSON implements the json.Unmarshaler interface.
+// UnmarshalJSON implements the [json.Unmarshaler] interface.
 // The time must be a quoted string in the RFC 3339 format.
 func (t *Time) UnmarshalJSON(data []byte) error {
 	if string(data) == "null" {
@@ -1389,7 +1389,7 @@ func (t *Time) UnmarshalJSON(data []byte) error {
 	return err
 }
 
-// MarshalText implements the encoding.TextMarshaler interface.
+// MarshalText implements the [encoding.TextMarshaler] interface.
 // The time is formatted in RFC 3339 format with sub-second precision.
 // If the timestamp cannot be represented as valid RFC 3339
 // (e.g., the year is out of range), then an error is reported.
@@ -1402,7 +1402,7 @@ func (t Time) MarshalText() ([]byte, error) {
 	return b, nil
 }
 
-// UnmarshalText implements the encoding.TextUnmarshaler interface.
+// UnmarshalText implements the [encoding.TextUnmarshaler] interface.
 // The time must be in the RFC 3339 format.
 func (t *Time) UnmarshalText(data []byte) error {
 	var err error

src/time/zoneinfo.go

@@ -99,7 +99,7 @@ func (l *Location) get() *Location {
 }
 
 // String returns a descriptive name for the time zone information,
-// corresponding to the name argument to LoadLocation or FixedZone.
+// corresponding to the name argument to [LoadLocation] or [FixedZone].
 func (l *Location) String() string {
 	return l.get().name
 }
@@ -107,7 +107,7 @@ func (l *Location) String() string {
 var unnamedFixedZones []*Location
 var unnamedFixedZonesOnce sync.Once
 
-// FixedZone returns a Location that always uses
+// FixedZone returns a [Location] that always uses
 // the given zone name and offset (seconds east of UTC).
 func FixedZone(name string, offset int) *Location {
 	// Most calls to FixedZone have an unnamed zone with an offset by the hour.