From f09db2bb9331f4b31afb867173b1773e6494af27 Mon Sep 17 00:00:00 2001 From: cui fliter Date: Sat, 14 Oct 2023 20:11:42 +0800 Subject: [PATCH] log: add available godoc link Change-Id: I80f1377631163cc5843379c36ca10b82fccd5709 Reviewed-on: https://go-review.googlesource.com/c/go/+/535086 Reviewed-by: David Chase Reviewed-by: Jonathan Amsterdam LUCI-TryBot-Result: Go LUCI --- src/log/log.go | 52 ++++++++++++++++++------------------ src/log/slog/attr.go | 6 ++--- src/log/slog/doc.go | 2 +- src/log/slog/handler.go | 2 +- src/log/slog/json_handler.go | 10 +++---- src/log/slog/level.go | 14 +++++----- src/log/slog/logger.go | 48 ++++++++++++++++----------------- src/log/slog/record.go | 10 +++---- src/log/slog/text_handler.go | 10 +++---- src/log/slog/value.go | 44 +++++++++++++++--------------- src/log/syslog/syslog.go | 30 ++++++++++----------- 11 files changed, 114 insertions(+), 114 deletions(-) diff --git a/src/log/log.go b/src/log/log.go index 9d5440ea3a..d4c9c1378f 100644 --- a/src/log/log.go +++ b/src/log/log.go @@ -2,7 +2,7 @@ // Use of this source code is governed by a BSD-style // license that can be found in the LICENSE file. -// Package log implements a simple logging package. It defines a type, Logger, +// Package log implements a simple logging package. It defines a type, [Logger], // with methods for formatting output. It also has a predefined 'standard' // Logger accessible through helper functions Print[f|ln], Fatal[f|ln], and // Panic[f|ln], which are easier to use than creating a Logger manually. @@ -10,7 +10,7 @@ // of each logged message. // Every log message is output on a separate line: if the message being // printed does not end in a newline, the logger will add one. -// The Fatal functions call os.Exit(1) after writing the log message. +// The Fatal functions call [os.Exit](1) after writing the log message. // The Panic functions call panic after writing the log message. package log @@ -25,7 +25,7 @@ import ( "time" ) -// These flags define which text to prefix to each log entry generated by the Logger. +// These flags define which text to prefix to each log entry generated by the [Logger]. // Bits are or'ed together to control what's printed. // With the exception of the Lmsgprefix flag, there is no // control over the order they appear (the order listed here) @@ -51,7 +51,7 @@ const ( ) // A Logger represents an active logging object that generates lines of -// output to an io.Writer. Each logging operation makes a single call to +// output to an [io.Writer]. Each logging operation makes a single call to // the Writer's Write method. A Logger can be used simultaneously from // multiple goroutines; it guarantees to serialize access to the Writer. type Logger struct { @@ -63,10 +63,10 @@ type Logger struct { isDiscard atomic.Bool } -// New creates a new Logger. The out variable sets the +// New creates a new [Logger]. The out variable sets the // destination to which log data will be written. // The prefix appears at the beginning of each generated log line, or -// after the log header if the Lmsgprefix flag is provided. +// after the log header if the [Lmsgprefix] flag is provided. // The flag argument defines the logging properties. func New(out io.Writer, prefix string, flag int) *Logger { l := new(Logger) @@ -255,7 +255,7 @@ func init() { } // Print calls l.Output to print to the logger. -// Arguments are handled in the manner of fmt.Print. +// Arguments are handled in the manner of [fmt.Print]. func (l *Logger) Print(v ...any) { l.output(0, 2, func(b []byte) []byte { return fmt.Append(b, v...) @@ -263,7 +263,7 @@ func (l *Logger) Print(v ...any) { } // Printf calls l.Output to print to the logger. -// Arguments are handled in the manner of fmt.Printf. +// Arguments are handled in the manner of [fmt.Printf]. func (l *Logger) Printf(format string, v ...any) { l.output(0, 2, func(b []byte) []byte { return fmt.Appendf(b, format, v...) @@ -271,26 +271,26 @@ func (l *Logger) Printf(format string, v ...any) { } // Println calls l.Output to print to the logger. -// Arguments are handled in the manner of fmt.Println. +// Arguments are handled in the manner of [fmt.Println]. func (l *Logger) Println(v ...any) { l.output(0, 2, func(b []byte) []byte { return fmt.Appendln(b, v...) }) } -// Fatal is equivalent to l.Print() followed by a call to os.Exit(1). +// Fatal is equivalent to l.Print() followed by a call to [os.Exit](1). func (l *Logger) Fatal(v ...any) { l.Output(2, fmt.Sprint(v...)) os.Exit(1) } -// Fatalf is equivalent to l.Printf() followed by a call to os.Exit(1). +// Fatalf is equivalent to l.Printf() followed by a call to [os.Exit](1). func (l *Logger) Fatalf(format string, v ...any) { l.Output(2, fmt.Sprintf(format, v...)) os.Exit(1) } -// Fatalln is equivalent to l.Println() followed by a call to os.Exit(1). +// Fatalln is equivalent to l.Println() followed by a call to [os.Exit](1). func (l *Logger) Fatalln(v ...any) { l.Output(2, fmt.Sprintln(v...)) os.Exit(1) @@ -318,13 +318,13 @@ func (l *Logger) Panicln(v ...any) { } // Flags returns the output flags for the logger. -// The flag bits are Ldate, Ltime, and so on. +// The flag bits are [Ldate], [Ltime], and so on. func (l *Logger) Flags() int { return int(l.flag.Load()) } // SetFlags sets the output flags for the logger. -// The flag bits are Ldate, Ltime, and so on. +// The flag bits are [Ldate], [Ltime], and so on. func (l *Logger) SetFlags(flag int) { l.flag.Store(int32(flag)) } @@ -355,13 +355,13 @@ func SetOutput(w io.Writer) { } // Flags returns the output flags for the standard logger. -// The flag bits are Ldate, Ltime, and so on. +// The flag bits are [Ldate], [Ltime], and so on. func Flags() int { return std.Flags() } // SetFlags sets the output flags for the standard logger. -// The flag bits are Ldate, Ltime, and so on. +// The flag bits are [Ldate], [Ltime], and so on. func SetFlags(flag int) { std.SetFlags(flag) } @@ -384,7 +384,7 @@ func Writer() io.Writer { // These functions write to the standard logger. // Print calls Output to print to the standard logger. -// Arguments are handled in the manner of fmt.Print. +// Arguments are handled in the manner of [fmt.Print]. func Print(v ...any) { std.output(0, 2, func(b []byte) []byte { return fmt.Append(b, v...) @@ -392,7 +392,7 @@ func Print(v ...any) { } // Printf calls Output to print to the standard logger. -// Arguments are handled in the manner of fmt.Printf. +// Arguments are handled in the manner of [fmt.Printf]. func Printf(format string, v ...any) { std.output(0, 2, func(b []byte) []byte { return fmt.Appendf(b, format, v...) @@ -400,46 +400,46 @@ func Printf(format string, v ...any) { } // Println calls Output to print to the standard logger. -// Arguments are handled in the manner of fmt.Println. +// Arguments are handled in the manner of [fmt.Println]. func Println(v ...any) { std.output(0, 2, func(b []byte) []byte { return fmt.Appendln(b, v...) }) } -// Fatal is equivalent to Print() followed by a call to os.Exit(1). +// Fatal is equivalent to [Print] followed by a call to [os.Exit](1). func Fatal(v ...any) { std.Output(2, fmt.Sprint(v...)) os.Exit(1) } -// Fatalf is equivalent to Printf() followed by a call to os.Exit(1). +// Fatalf is equivalent to [Printf] followed by a call to [os.Exit](1). func Fatalf(format string, v ...any) { std.Output(2, fmt.Sprintf(format, v...)) os.Exit(1) } -// Fatalln is equivalent to Println() followed by a call to os.Exit(1). +// Fatalln is equivalent to [Println] followed by a call to [os.Exit](1). func Fatalln(v ...any) { std.Output(2, fmt.Sprintln(v...)) os.Exit(1) } -// Panic is equivalent to Print() followed by a call to panic(). +// Panic is equivalent to [Print] followed by a call to panic(). func Panic(v ...any) { s := fmt.Sprint(v...) std.Output(2, s) panic(s) } -// Panicf is equivalent to Printf() followed by a call to panic(). +// Panicf is equivalent to [Printf] followed by a call to panic(). func Panicf(format string, v ...any) { s := fmt.Sprintf(format, v...) std.Output(2, s) panic(s) } -// Panicln is equivalent to Println() followed by a call to panic(). +// Panicln is equivalent to [Println] followed by a call to panic(). func Panicln(v ...any) { s := fmt.Sprintln(v...) std.Output(2, s) @@ -451,7 +451,7 @@ func Panicln(v ...any) { // Logger. A newline is appended if the last character of s is not // already a newline. Calldepth is the count of the number of // frames to skip when computing the file name and line number -// if Llongfile or Lshortfile is set; a value of 1 will print the details +// if [Llongfile] or [Lshortfile] is set; a value of 1 will print the details // for the caller of Output. func Output(calldepth int, s string) error { return std.Output(calldepth+1, s) // +1 for this frame. diff --git a/src/log/slog/attr.go b/src/log/slog/attr.go index 90e343b319..2f459467cb 100644 --- a/src/log/slog/attr.go +++ b/src/log/slog/attr.go @@ -46,18 +46,18 @@ func Bool(key string, v bool) Attr { return Attr{key, BoolValue(v)} } -// Time returns an Attr for a time.Time. +// Time returns an Attr for a [time.Time]. // It discards the monotonic portion. func Time(key string, v time.Time) Attr { return Attr{key, TimeValue(v)} } -// Duration returns an Attr for a time.Duration. +// Duration returns an Attr for a [time.Duration]. func Duration(key string, v time.Duration) Attr { return Attr{key, DurationValue(v)} } -// Group returns an Attr for a Group Value. +// Group returns an Attr for a Group [Value]. // The first argument is the key; the remaining arguments // are converted to Attrs as in [Logger.Log]. // diff --git a/src/log/slog/doc.go b/src/log/slog/doc.go index c3f90cbbac..001559326b 100644 --- a/src/log/slog/doc.go +++ b/src/log/slog/doc.go @@ -222,7 +222,7 @@ details. A LogValue method may return a Value that itself implements [LogValuer]. The [Value.Resolve] method handles these cases carefully, avoiding infinite loops and unbounded recursion. -Handler authors and others may wish to use Value.Resolve instead of calling LogValue directly. +Handler authors and others may wish to use [Value.Resolve] instead of calling LogValue directly. # Wrapping output methods diff --git a/src/log/slog/handler.go b/src/log/slog/handler.go index 03d631c0ac..a6c643cdb9 100644 --- a/src/log/slog/handler.go +++ b/src/log/slog/handler.go @@ -125,7 +125,7 @@ func (h *defaultHandler) WithGroup(name string) Handler { return &defaultHandler{h.ch.withGroup(name), h.output} } -// HandlerOptions are options for a TextHandler or JSONHandler. +// HandlerOptions are options for a [TextHandler] or [JSONHandler]. // A zero HandlerOptions consists entirely of default values. type HandlerOptions struct { // AddSource causes the handler to compute the source code position diff --git a/src/log/slog/json_handler.go b/src/log/slog/json_handler.go index 1c51ab05ff..c3b4882f41 100644 --- a/src/log/slog/json_handler.go +++ b/src/log/slog/json_handler.go @@ -18,13 +18,13 @@ import ( "unicode/utf8" ) -// JSONHandler is a Handler that writes Records to an io.Writer as +// JSONHandler is a [Handler] that writes Records to an [io.Writer] as // line-delimited JSON objects. type JSONHandler struct { *commonHandler } -// NewJSONHandler creates a JSONHandler that writes to w, +// NewJSONHandler creates a [JSONHandler] that writes to w, // using the given options. // If opts is nil, the default options are used. func NewJSONHandler(w io.Writer, opts *HandlerOptions) *JSONHandler { @@ -47,7 +47,7 @@ func (h *JSONHandler) Enabled(_ context.Context, level Level) bool { return h.commonHandler.enabled(level) } -// WithAttrs returns a new JSONHandler whose attributes consists +// WithAttrs returns a new [JSONHandler] whose attributes consists // of h's attributes followed by attrs. func (h *JSONHandler) WithAttrs(attrs []Attr) Handler { return &JSONHandler{commonHandler: h.commonHandler.withAttrs(attrs)} @@ -57,7 +57,7 @@ func (h *JSONHandler) WithGroup(name string) Handler { return &JSONHandler{commonHandler: h.commonHandler.withGroup(name)} } -// Handle formats its argument Record as a JSON object on a single line. +// Handle formats its argument [Record] as a JSON object on a single line. // // If the Record's time is zero, the time is omitted. // Otherwise, the key is "time" @@ -81,7 +81,7 @@ func (h *JSONHandler) WithGroup(name string) Handler { // First, an Attr whose Value is of type error is formatted as a string, by // calling its Error method. Only errors in Attrs receive this special treatment, // not errors embedded in structs, slices, maps or other data structures that -// are processed by the encoding/json package. +// are processed by the [encoding/json] package. // // Second, an encoding failure does not cause Handle to return an error. // Instead, the error message is formatted as a string. diff --git a/src/log/slog/level.go b/src/log/slog/level.go index cd1213af64..351d4fa159 100644 --- a/src/log/slog/level.go +++ b/src/log/slog/level.go @@ -146,14 +146,14 @@ func (l *Level) parse(s string) (err error) { } // Level returns the receiver. -// It implements Leveler. +// It implements [Leveler]. func (l Level) Level() Level { return l } -// A LevelVar is a Level variable, to allow a Handler level to change +// A LevelVar is a [Level] variable, to allow a [Handler] level to change // dynamically. -// It implements Leveler as well as a Set method, +// It implements [Leveler] as well as a Set method, // and it is safe for use by multiple goroutines. -// The zero LevelVar corresponds to LevelInfo. +// The zero LevelVar corresponds to [LevelInfo]. type LevelVar struct { val atomic.Int64 } @@ -189,12 +189,12 @@ func (v *LevelVar) UnmarshalText(data []byte) error { return nil } -// A Leveler provides a Level value. +// A Leveler provides a [Level] value. // // As Level itself implements Leveler, clients typically supply -// a Level value wherever a Leveler is needed, such as in HandlerOptions. +// a Level value wherever a Leveler is needed, such as in [HandlerOptions]. // Clients who need to vary the level dynamically can provide a more complex -// Leveler implementation such as *LevelVar. +// Leveler implementation such as *[LevelVar]. type Leveler interface { Level() Level } diff --git a/src/log/slog/logger.go b/src/log/slog/logger.go index a42b0a4bcc..fceafe0cba 100644 --- a/src/log/slog/logger.go +++ b/src/log/slog/logger.go @@ -20,12 +20,12 @@ func init() { defaultLogger.Store(New(newDefaultHandler(loginternal.DefaultOutput))) } -// Default returns the default Logger. +// Default returns the default [Logger]. func Default() *Logger { return defaultLogger.Load() } -// SetDefault makes l the default Logger. +// SetDefault makes l the default [Logger]. // After this call, output from the log package's default Logger -// (as with [log.Print], etc.) will be logged at LevelInfo using l's Handler. +// (as with [log.Print], etc.) will be logged at [LevelInfo] using l's Handler. func SetDefault(l *Logger) { defaultLogger.Store(l) // If the default's handler is a defaultHandler, then don't use a handleWriter, @@ -72,7 +72,7 @@ func (w *handlerWriter) Write(buf []byte) (int, error) { // A Logger records structured information about each call to its // Log, Debug, Info, Warn, and Error methods. -// For each call, it creates a Record and passes it to a Handler. +// For each call, it creates a [Record] and passes it to a [Handler]. // // To create a new Logger, call [New] or a Logger method // that begins "With". @@ -124,7 +124,7 @@ func New(h Handler) *Logger { return &Logger{handler: h} } -// With calls Logger.With on the default logger. +// With calls [Logger.With] on the default logger. func With(args ...any) *Logger { return Default().With(args...) } @@ -137,7 +137,7 @@ func (l *Logger) Enabled(ctx context.Context, level Level) bool { return l.Handler().Enabled(ctx, level) } -// NewLogLogger returns a new log.Logger such that each call to its Output method +// NewLogLogger returns a new [log.Logger] such that each call to its Output method // dispatches a Record to the specified handler. The logger acts as a bridge from // the older log API to newer structured logging handlers. func NewLogLogger(h Handler, level Level) *log.Logger { @@ -163,42 +163,42 @@ func (l *Logger) LogAttrs(ctx context.Context, level Level, msg string, attrs .. l.logAttrs(ctx, level, msg, attrs...) } -// Debug logs at LevelDebug. +// Debug logs at [LevelDebug]. func (l *Logger) Debug(msg string, args ...any) { l.log(context.Background(), LevelDebug, msg, args...) } -// DebugContext logs at LevelDebug with the given context. +// DebugContext logs at [LevelDebug] with the given context. func (l *Logger) DebugContext(ctx context.Context, msg string, args ...any) { l.log(ctx, LevelDebug, msg, args...) } -// Info logs at LevelInfo. +// Info logs at [LevelInfo]. func (l *Logger) Info(msg string, args ...any) { l.log(context.Background(), LevelInfo, msg, args...) } -// InfoContext logs at LevelInfo with the given context. +// InfoContext logs at [LevelInfo] with the given context. func (l *Logger) InfoContext(ctx context.Context, msg string, args ...any) { l.log(ctx, LevelInfo, msg, args...) } -// Warn logs at LevelWarn. +// Warn logs at [LevelWarn]. func (l *Logger) Warn(msg string, args ...any) { l.log(context.Background(), LevelWarn, msg, args...) } -// WarnContext logs at LevelWarn with the given context. +// WarnContext logs at [LevelWarn] with the given context. func (l *Logger) WarnContext(ctx context.Context, msg string, args ...any) { l.log(ctx, LevelWarn, msg, args...) } -// Error logs at LevelError. +// Error logs at [LevelError]. func (l *Logger) Error(msg string, args ...any) { l.log(context.Background(), LevelError, msg, args...) } -// ErrorContext logs at LevelError with the given context. +// ErrorContext logs at [LevelError] with the given context. func (l *Logger) ErrorContext(ctx context.Context, msg string, args ...any) { l.log(ctx, LevelError, msg, args...) } @@ -245,52 +245,52 @@ func (l *Logger) logAttrs(ctx context.Context, level Level, msg string, attrs .. _ = l.Handler().Handle(ctx, r) } -// Debug calls Logger.Debug on the default logger. +// Debug calls [Logger.Debug] on the default logger. func Debug(msg string, args ...any) { Default().log(context.Background(), LevelDebug, msg, args...) } -// DebugContext calls Logger.DebugContext on the default logger. +// DebugContext calls [Logger.DebugContext] on the default logger. func DebugContext(ctx context.Context, msg string, args ...any) { Default().log(ctx, LevelDebug, msg, args...) } -// Info calls Logger.Info on the default logger. +// Info calls [Logger.Info] on the default logger. func Info(msg string, args ...any) { Default().log(context.Background(), LevelInfo, msg, args...) } -// InfoContext calls Logger.InfoContext on the default logger. +// InfoContext calls [Logger.InfoContext] on the default logger. func InfoContext(ctx context.Context, msg string, args ...any) { Default().log(ctx, LevelInfo, msg, args...) } -// Warn calls Logger.Warn on the default logger. +// Warn calls [Logger.Warn] on the default logger. func Warn(msg string, args ...any) { Default().log(context.Background(), LevelWarn, msg, args...) } -// WarnContext calls Logger.WarnContext on the default logger. +// WarnContext calls [Logger.WarnContext] on the default logger. func WarnContext(ctx context.Context, msg string, args ...any) { Default().log(ctx, LevelWarn, msg, args...) } -// Error calls Logger.Error on the default logger. +// Error calls [Logger.Error] on the default logger. func Error(msg string, args ...any) { Default().log(context.Background(), LevelError, msg, args...) } -// ErrorContext calls Logger.ErrorContext on the default logger. +// ErrorContext calls [Logger.ErrorContext] on the default logger. func ErrorContext(ctx context.Context, msg string, args ...any) { Default().log(ctx, LevelError, msg, args...) } -// Log calls Logger.Log on the default logger. +// Log calls [Logger.Log] on the default logger. func Log(ctx context.Context, level Level, msg string, args ...any) { Default().log(ctx, level, msg, args...) } -// LogAttrs calls Logger.LogAttrs on the default logger. +// LogAttrs calls [Logger.LogAttrs] on the default logger. func LogAttrs(ctx context.Context, level Level, msg string, attrs ...Attr) { Default().logAttrs(ctx, level, msg, attrs...) } diff --git a/src/log/slog/record.go b/src/log/slog/record.go index ea57c81c50..8afe253bc8 100644 --- a/src/log/slog/record.go +++ b/src/log/slog/record.go @@ -50,7 +50,7 @@ type Record struct { back []Attr } -// NewRecord creates a Record from the given arguments. +// NewRecord creates a [Record] from the given arguments. // Use [Record.AddAttrs] to add attributes to the Record. // // NewRecord is intended for logging APIs that want to support a [Handler] as @@ -72,12 +72,12 @@ func (r Record) Clone() Record { return r } -// NumAttrs returns the number of attributes in the Record. +// NumAttrs returns the number of attributes in the [Record]. func (r Record) NumAttrs() int { return r.nFront + len(r.back) } -// Attrs calls f on each Attr in the Record. +// Attrs calls f on each Attr in the [Record]. // Iteration stops if f returns false. func (r Record) Attrs(f func(Attr) bool) { for i := 0; i < r.nFront; i++ { @@ -92,7 +92,7 @@ func (r Record) Attrs(f func(Attr) bool) { } } -// AddAttrs appends the given Attrs to the Record's list of Attrs. +// AddAttrs appends the given Attrs to the [Record]'s list of Attrs. // It omits empty groups. func (r *Record) AddAttrs(attrs ...Attr) { var i int @@ -124,7 +124,7 @@ func (r *Record) AddAttrs(attrs ...Attr) { } // Add converts the args to Attrs as described in [Logger.Log], -// then appends the Attrs to the Record's list of Attrs. +// then appends the Attrs to the [Record]'s list of Attrs. // It omits empty groups. func (r *Record) Add(args ...any) { var a Attr diff --git a/src/log/slog/text_handler.go b/src/log/slog/text_handler.go index 58edb2f66d..6819e633bb 100644 --- a/src/log/slog/text_handler.go +++ b/src/log/slog/text_handler.go @@ -16,13 +16,13 @@ import ( "unicode/utf8" ) -// TextHandler is a Handler that writes Records to an io.Writer as a +// TextHandler is a [Handler] that writes Records to an [io.Writer] as a // sequence of key=value pairs separated by spaces and followed by a newline. type TextHandler struct { *commonHandler } -// NewTextHandler creates a TextHandler that writes to w, +// NewTextHandler creates a [TextHandler] that writes to w, // using the given options. // If opts is nil, the default options are used. func NewTextHandler(w io.Writer, opts *HandlerOptions) *TextHandler { @@ -45,7 +45,7 @@ func (h *TextHandler) Enabled(_ context.Context, level Level) bool { return h.commonHandler.enabled(level) } -// WithAttrs returns a new TextHandler whose attributes consists +// WithAttrs returns a new [TextHandler] whose attributes consists // of h's attributes followed by attrs. func (h *TextHandler) WithAttrs(attrs []Attr) Handler { return &TextHandler{commonHandler: h.commonHandler.withAttrs(attrs)} @@ -55,7 +55,7 @@ func (h *TextHandler) WithGroup(name string) Handler { return &TextHandler{commonHandler: h.commonHandler.withGroup(name)} } -// Handle formats its argument Record as a single line of space-separated +// Handle formats its argument [Record] as a single line of space-separated // key=value items. // // If the Record's time is zero, the time is omitted. @@ -75,7 +75,7 @@ func (h *TextHandler) WithGroup(name string) Handler { // [HandlerOptions.ReplaceAttr]. // // If a value implements [encoding.TextMarshaler], the result of MarshalText is -// written. Otherwise, the result of fmt.Sprint is written. +// written. Otherwise, the result of [fmt.Sprint] is written. // // Keys and values are quoted with [strconv.Quote] if they contain Unicode space // characters, non-printing characters, '"' or '='. diff --git a/src/log/slog/value.go b/src/log/slog/value.go index b6072c5f7b..d278d9b923 100644 --- a/src/log/slog/value.go +++ b/src/log/slog/value.go @@ -40,7 +40,7 @@ type ( groupptr *Attr // used in Value.any when the Value is a []Attr ) -// Kind is the kind of a Value. +// Kind is the kind of a [Value]. type Kind int // The following list is sorted alphabetically, but it's also important that @@ -105,32 +105,32 @@ func (v Value) Kind() Kind { //////////////// Constructors -// StringValue returns a new Value for a string. +// StringValue returns a new [Value] for a string. func StringValue(value string) Value { return Value{num: uint64(len(value)), any: stringptr(unsafe.StringData(value))} } -// IntValue returns a Value for an int. +// IntValue returns a [Value] for an int. func IntValue(v int) Value { return Int64Value(int64(v)) } -// Int64Value returns a Value for an int64. +// Int64Value returns a [Value] for an int64. func Int64Value(v int64) Value { return Value{num: uint64(v), any: KindInt64} } -// Uint64Value returns a Value for a uint64. +// Uint64Value returns a [Value] for a uint64. func Uint64Value(v uint64) Value { return Value{num: v, any: KindUint64} } -// Float64Value returns a Value for a floating-point number. +// Float64Value returns a [Value] for a floating-point number. func Float64Value(v float64) Value { return Value{num: math.Float64bits(v), any: KindFloat64} } -// BoolValue returns a Value for a bool. +// BoolValue returns a [Value] for a bool. func BoolValue(v bool) Value { u := uint64(0) if v { @@ -143,7 +143,7 @@ func BoolValue(v bool) Value { // Values. (No user-provided value has this type.) type timeLocation *time.Location -// TimeValue returns a Value for a time.Time. +// TimeValue returns a [Value] for a [time.Time]. // It discards the monotonic portion. func TimeValue(v time.Time) Value { if v.IsZero() { @@ -156,12 +156,12 @@ func TimeValue(v time.Time) Value { return Value{num: uint64(v.UnixNano()), any: timeLocation(v.Location())} } -// DurationValue returns a Value for a time.Duration. +// DurationValue returns a [Value] for a [time.Duration]. func DurationValue(v time.Duration) Value { return Value{num: uint64(v.Nanoseconds()), any: KindDuration} } -// GroupValue returns a new Value for a list of Attrs. +// GroupValue returns a new [Value] for a list of Attrs. // The caller must not subsequently mutate the argument slice. func GroupValue(as ...Attr) Value { // Remove empty groups. @@ -190,21 +190,21 @@ func countEmptyGroups(as []Attr) int { return n } -// AnyValue returns a Value for the supplied value. +// AnyValue returns a [Value] for the supplied value. // // If the supplied value is of type Value, it is returned // unmodified. // // Given a value of one of Go's predeclared string, bool, or // (non-complex) numeric types, AnyValue returns a Value of kind -// String, Bool, Uint64, Int64, or Float64. The width of the -// original numeric type is not preserved. +// [KindString], [KindBool], [KindUint64], [KindInt64], or [KindFloat64]. +// The width of the original numeric type is not preserved. // -// Given a time.Time or time.Duration value, AnyValue returns a Value of kind -// KindTime or KindDuration. The monotonic time is not preserved. +// Given a [time.Time] or [time.Duration] value, AnyValue returns a Value of kind +// [KindTime] or [KindDuration]. The monotonic time is not preserved. // // For nil, or values of all other types, including named types whose -// underlying type is numeric, AnyValue returns a value of kind KindAny. +// underlying type is numeric, AnyValue returns a value of kind [KindAny]. func AnyValue(v any) Value { switch v := v.(type) { case string: @@ -285,7 +285,7 @@ func (v Value) Any() any { } } -// String returns Value's value as a string, formatted like fmt.Sprint. Unlike +// String returns Value's value as a string, formatted like [fmt.Sprint]. Unlike // the methods Int64, Float64, and so on, which panic if v is of the // wrong kind, String never panics. func (v Value) String() string { @@ -331,7 +331,7 @@ func (v Value) bool() bool { return v.num == 1 } -// Duration returns v's value as a time.Duration. It panics +// Duration returns v's value as a [time.Duration]. It panics // if v is not a time.Duration. func (v Value) Duration() time.Duration { if g, w := v.Kind(), KindDuration; g != w { @@ -359,7 +359,7 @@ func (v Value) float() float64 { return math.Float64frombits(v.num) } -// Time returns v's value as a time.Time. It panics +// Time returns v's value as a [time.Time]. It panics // if v is not a time.Time. func (v Value) Time() time.Time { if g, w := v.Kind(), KindTime; g != w { @@ -383,7 +383,7 @@ func (v Value) LogValuer() LogValuer { } // Group returns v's value as a []Attr. -// It panics if v's Kind is not KindGroup. +// It panics if v's [Kind] is not [KindGroup]. func (v Value) Group() []Attr { if sp, ok := v.any.(groupptr); ok { return unsafe.Slice((*Attr)(sp), v.num) @@ -470,13 +470,13 @@ type LogValuer interface { const maxLogValues = 100 -// Resolve repeatedly calls LogValue on v while it implements LogValuer, +// Resolve repeatedly calls LogValue on v while it implements [LogValuer], // and returns the result. // If v resolves to a group, the group's attributes' values are not recursively // resolved. // If the number of LogValue calls exceeds a threshold, a Value containing an // error is returned. -// Resolve's return value is guaranteed not to be of Kind KindLogValuer. +// Resolve's return value is guaranteed not to be of Kind [KindLogValuer]. func (v Value) Resolve() (rv Value) { orig := v defer func() { diff --git a/src/log/syslog/syslog.go b/src/log/syslog/syslog.go index 03e5263d3e..362dd950ba 100644 --- a/src/log/syslog/syslog.go +++ b/src/log/syslog/syslog.go @@ -18,9 +18,9 @@ import ( ) // The Priority is a combination of the syslog facility and -// severity. For example, LOG_ALERT | LOG_FTP sends an alert severity -// message from the FTP facility. The default severity is LOG_EMERG; -// the default facility is LOG_KERN. +// severity. For example, [LOG_ALERT] | [LOG_FTP] sends an alert severity +// message from the FTP facility. The default severity is [LOG_EMERG]; +// the default facility is [LOG_KERN]. type Priority int const severityMask = 0x07 @@ -103,7 +103,7 @@ type netConn struct { // New establishes a new connection to the system log daemon. Each // write to the returned writer sends a log message with the given // priority (a combination of the syslog facility and severity) and -// prefix tag. If tag is empty, the os.Args[0] is used. +// prefix tag. If tag is empty, the [os.Args][0] is used. func New(priority Priority, tag string) (*Writer, error) { return Dial("", "", priority, tag) } @@ -111,7 +111,7 @@ func New(priority Priority, tag string) (*Writer, error) { // Dial establishes a connection to a log daemon by connecting to // address raddr on the specified network. Each write to the returned // writer sends a log message with the facility and severity -// (from priority) and tag. If tag is empty, the os.Args[0] is used. +// (from priority) and tag. If tag is empty, the [os.Args][0] is used. // If network is empty, Dial will connect to the local syslog server. // Otherwise, see the documentation for net.Dial for valid values // of network and raddr. @@ -191,56 +191,56 @@ func (w *Writer) Close() error { return nil } -// Emerg logs a message with severity LOG_EMERG, ignoring the severity +// Emerg logs a message with severity [LOG_EMERG], ignoring the severity // passed to New. func (w *Writer) Emerg(m string) error { _, err := w.writeAndRetry(LOG_EMERG, m) return err } -// Alert logs a message with severity LOG_ALERT, ignoring the severity +// Alert logs a message with severity [LOG_ALERT], ignoring the severity // passed to New. func (w *Writer) Alert(m string) error { _, err := w.writeAndRetry(LOG_ALERT, m) return err } -// Crit logs a message with severity LOG_CRIT, ignoring the severity +// Crit logs a message with severity [LOG_CRIT], ignoring the severity // passed to New. func (w *Writer) Crit(m string) error { _, err := w.writeAndRetry(LOG_CRIT, m) return err } -// Err logs a message with severity LOG_ERR, ignoring the severity +// Err logs a message with severity [LOG_ERR], ignoring the severity // passed to New. func (w *Writer) Err(m string) error { _, err := w.writeAndRetry(LOG_ERR, m) return err } -// Warning logs a message with severity LOG_WARNING, ignoring the +// Warning logs a message with severity [LOG_WARNING], ignoring the // severity passed to New. func (w *Writer) Warning(m string) error { _, err := w.writeAndRetry(LOG_WARNING, m) return err } -// Notice logs a message with severity LOG_NOTICE, ignoring the +// Notice logs a message with severity [LOG_NOTICE], ignoring the // severity passed to New. func (w *Writer) Notice(m string) error { _, err := w.writeAndRetry(LOG_NOTICE, m) return err } -// Info logs a message with severity LOG_INFO, ignoring the severity +// Info logs a message with severity [LOG_INFO], ignoring the severity // passed to New. func (w *Writer) Info(m string) error { _, err := w.writeAndRetry(LOG_INFO, m) return err } -// Debug logs a message with severity LOG_DEBUG, ignoring the severity +// Debug logs a message with severity [LOG_DEBUG], ignoring the severity // passed to New. func (w *Writer) Debug(m string) error { _, err := w.writeAndRetry(LOG_DEBUG, m) @@ -305,10 +305,10 @@ func (n *netConn) close() error { return n.conn.Close() } -// NewLogger creates a log.Logger whose output is written to the +// NewLogger creates a [log.Logger] whose output is written to the // system log service with the specified priority, a combination of // the syslog facility and severity. The logFlag argument is the flag -// set passed through to log.New to create the Logger. +// set passed through to [log.New] to create the Logger. func NewLogger(p Priority, logFlag int) (*log.Logger, error) { s, err := New(p, "") if err != nil {