From deb2f89eb16929819cddbd293240f06f5f396bc1 Mon Sep 17 00:00:00 2001 From: cui fliter Date: Sat, 4 Nov 2023 16:35:22 +0800 Subject: [PATCH] time: add available godoc link Change-Id: Idfe9cf2f2e4750d6673455f98deef2efc2d292a6 Reviewed-on: https://go-review.googlesource.com/c/go/+/539837 Reviewed-by: Ian Lance Taylor LUCI-TryBot-Result: Go LUCI Reviewed-by: Dmitri Shuralyov Auto-Submit: Ian Lance Taylor --- src/time/format.go | 34 +++++++++++++++--------------- src/time/sleep.go | 20 +++++++++--------- src/time/tick.go | 8 +++---- src/time/time.go | 50 ++++++++++++++++++++++---------------------- src/time/zoneinfo.go | 4 ++-- 5 files changed, 58 insertions(+), 58 deletions(-) diff --git a/src/time/format.go b/src/time/format.go index 7fbeddb540..9115609f60 100644 --- a/src/time/format.go +++ b/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 { diff --git a/src/time/sleep.go b/src/time/sleep.go index 73fdf2a782..2c6495d93a 100644 --- a/src/time/sleep.go +++ b/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 { diff --git a/src/time/tick.go b/src/time/tick.go index 935b61a8ee..057a9069ea 100644 --- a/src/time/tick.go +++ b/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. diff --git a/src/time/time.go b/src/time/time.go index 2ca1cdbb72..8c24e1c481 100644 --- a/src/time/time.go +++ b/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 diff --git a/src/time/zoneinfo.go b/src/time/zoneinfo.go index c8d1762302..0fe13630e9 100644 --- a/src/time/zoneinfo.go +++ b/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. -- 2.48.1