docs: refresh and update style

Author: tmzane

env.go

@@ -11,27 +11,21 @@ import (
 	"strings"
 )
 
-// ErrInvalidArgument is returned when the argument provided to
-// [Load]/[LoadFrom] is invalid.
+// ErrInvalidArgument is returned when the argument provided to [Load]/[LoadFrom] is invalid.
 var ErrInvalidArgument = errors.New("env: argument must be a non-nil struct pointer")
 
-// ErrEmptyTagName is returned when the `env` tag is found but the name of the
-// environment variable is empty.
+// ErrEmptyTagName is returned when the `env` tag is found but the name of the environment variable is empty.
 var ErrEmptyTagName = errors.New("env: empty tag name is not allowed")
 
-// ErrUnsupportedType is returned when the provided struct contains a field of
-// an unsupported type.
+// ErrUnsupportedType is returned when the provided struct contains a field of an unsupported type.
 var ErrUnsupportedType = errors.New("env: unsupported type")
 
-// ErrInvalidTagOption is returned when the `env` tag contains an invalid
-// option, e.g. `env:"VAR,invalid"`.
+// ErrInvalidTagOption is returned when the `env` tag contains an invalid option, e.g. `env:"VAR,invalid"`.
 var ErrInvalidTagOption = errors.New("env: invalid tag option")
 
-// NotSetError is returned when environment variables are marked as required but
-// not set.
+// NotSetError is returned when environment variables are marked as required but not set.
 type NotSetError struct {
-	// Names is a slice of the names of the missing required environment
-	// variables.
+	// Names is a slice of the names of the missing required environment variables.
 	Names []string
 }
 
@@ -40,15 +34,13 @@ func (e *NotSetError) Error() string {
 	return fmt.Sprintf("env: %v are required but not set", e.Names)
 }
 
-// Load loads environment variables into the provided struct using the [OS]
-// [Provider] as their source. To specify a custom [Provider], use the
-// [LoadFrom] function. dst must be a non-nil struct pointer, otherwise Load
-// returns [ErrInvalidArgument].
+// Load loads environment variables into the provided struct using the [OS] [Provider] as their source.
+// To specify a custom [Provider], use the [LoadFrom] function.
+// dst must be a non-nil struct pointer, otherwise Load returns [ErrInvalidArgument].
 //
-// The struct fields must have the `env:"VAR"` struct tag, where VAR is the name
-// of the corresponding environment variable. Unexported fields are ignored. If
-// the tag is found but the name of the environment variable is empty, the
-// error will be [ErrEmptyTagName].
+// The struct fields must have the `env:"VAR"` struct tag, where VAR is the name of the corresponding environment variable.
+// Unexported fields are ignored.
+// If the tag is found but the name of the environment variable is empty, the error will be [ErrEmptyTagName].
 //
 // # Supported types
 //
@@ -60,33 +52,28 @@ func (e *NotSetError) Error() string {
 //   - [encoding.TextUnmarshaler]
 //   - slices of any type above (space is the default separator for values)
 //
-// See the [strconv].Parse* functions for parsing rules. Implementing the
-// [encoding.TextUnmarshaler] interface is enough to use any user-defined type.
-// Nested structs of any depth level are supported, only the leaves of the
-// config tree must have the `env` tag. If a field of an unsupported type is
-// found, the error will be [ErrUnsupportedType].
+// See the [strconv].Parse* functions for parsing rules.
+// Implementing the [encoding.TextUnmarshaler] interface is enough to use any user-defined type.
+// Nested structs of any depth level are supported, only the leaves of the config tree must have the `env` tag.
+// If a field of an unsupported type is found, the error will be [ErrUnsupportedType].
 //
 // # Default values
 //
-// Default values can be specified either using the `default` struct tag (has a
-// higher priority) or by initializing the struct fields directly.
+// Default values can be specified either using the `default` struct tag (has a higher priority) or by initializing the struct fields directly.
 //
 // # Per-variable options
 //
-// The name of the environment variable can be followed by comma-separated
-// options in the form of `env:"VAR,option1,option2,..."`:
+// The name of the environment variable can be followed by comma-separated options in the form of `env:"VAR,option1,option2,..."`:
 //
 //   - required: marks the environment variable as required
 //   - expand: expands the value of the environment variable using [os.Expand]
 //
-// If environment variables are marked as required but not set, an error of type
-// [NotSetError] will be returned. If the tag contains an invalid option, the
-// error will be [ErrInvalidTagOption].
+// If environment variables are marked as required but not set, an error of type [NotSetError] will be returned.
+// If the tag contains an invalid option, the error will be [ErrInvalidTagOption].
 //
 // # Global options
 //
-// In addition to the per-variable options, [env] also supports global options
-// that apply to all variables:
+// In addition to the per-variable options, [env] also supports global options that apply to all variables:
 //
 //   - [WithPrefix]: sets prefix for each environment variable
 //   - [WithSliceSeparator]: sets custom separator to parse slice values
@@ -98,44 +85,40 @@ func Load(dst any, opts ...Option) error {
 	return newLoader(OS, opts...).loadVars(dst)
 }
 
-// LoadFrom loads environment variables into the provided struct using the
-// specified [Provider] as their source. See [Load] documentation for more
-// details.
+// LoadFrom loads environment variables into the provided struct using the specified [Provider] as their source.
+// See [Load] documentation for more details.
 func LoadFrom(p Provider, dst any, opts ...Option) error {
 	return newLoader(p, opts...).loadVars(dst)
 }
 
 // Option allows to configure the behaviour of the [Load]/[LoadFrom] functions.
 type Option func(*loader)
 
-// WithPrefix configures [Load]/[LoadFrom] to automatically add the provided
-// prefix to each environment variable. By default, no prefix is configured.
+// WithPrefix configures [Load]/[LoadFrom] to automatically add the provided prefix to each environment variable.
+// By default, no prefix is configured.
 func WithPrefix(prefix string) Option {
 	return func(l *loader) { l.prefix = prefix }
 }
 
-// WithSliceSeparator configures [Load]/[LoadFrom] to use the provided separator
-// when parsing slice values. The default one is space.
+// WithSliceSeparator configures [Load]/[LoadFrom] to use the provided separator when parsing slice values.
+// The default one is space.
 func WithSliceSeparator(sep string) Option {
 	return func(l *loader) { l.sliceSep = sep }
 }
 
-// WithStrictMode configures [Load]/[LoadFrom] to treat all environment
-// variables without the `default` tag as required. By default, strict mode is
-// disabled.
+// WithStrictMode configures [Load]/[LoadFrom] to treat all environment variables without the `default` tag as required.
+// By default, strict mode is disabled.
 func WithStrictMode() Option {
 	return func(l *loader) { l.strictMode = true }
 }
 
-// WithUsageOnError configures [Load]/[LoadFrom] to write an auto-generated
-// usage message to the provided [io.Writer], if an error occurs while loading
-// environment variables. The message format can be changed by assigning the
-// global [Usage] variable to a custom implementation.
+// WithUsageOnError configures [Load]/[LoadFrom] to write an auto-generated usage message to the provided [io.Writer],
+// if an error occurs while loading environment variables.
+// The message format can be changed by assigning the global [Usage] variable to a custom implementation.
 func WithUsageOnError(w io.Writer) Option {
 	return func(l *loader) { l.usageOutput = w }
 }
 
-// loader is an environment variables loader.
 type loader struct {
 	provider    Provider
 	prefix      string
@@ -144,8 +127,6 @@ type loader struct {
 	usageOutput io.Writer
 }
 
-// newLoader creates a new loader with the specified [Provider] and applies the
-// provided options, which override the default settings.
 func newLoader(p Provider, opts ...Option) *loader {
 	l := loader{
 		provider:    p,
@@ -160,7 +141,6 @@ func newLoader(p Provider, opts ...Option) *loader {
 	return &l
 }
 
-// loadVars loads environment variables into the provided struct.
 func (l *loader) loadVars(dst any) (err error) {
 	rv := reflect.ValueOf(dst)
 	if !structPtr(rv) {
@@ -178,8 +158,7 @@ func (l *loader) loadVars(dst any) (err error) {
 		}
 	}()
 
-	// accumulate missing required variables
-	// to return NotSetError after the loop is finished.
+	// accumulate missing required variables to return NotSetError after the loop is finished.
 	var notset []string
 
 	for _, v := range vars {
@@ -191,8 +170,6 @@ func (l *loader) loadVars(dst any) (err error) {
 				continue
 			}
 			// ...otherwise, use the default value.
-			// TODO: actually, there is no need to set a default value
-			// if it has been obtained from the initialized struct field.
 			value = v.Default
 		}
 
@@ -213,16 +190,13 @@ func (l *loader) loadVars(dst any) (err error) {
 	return nil
 }
 
-// parseVars parses environment variables from the fields of the provided
-// struct.
 func (l *loader) parseVars(v reflect.Value) ([]Var, error) {
 	var vars []Var
 
 	for i := 0; i < v.NumField(); i++ {
 		field := v.Field(i)
 		if !field.CanSet() {
-			// skip unexported fields.
-			continue
+			continue // skip unexported fields.
 		}
 
 		// special case: a nested struct, parse its fields recursively.
@@ -238,8 +212,7 @@ func (l *loader) parseVars(v reflect.Value) ([]Var, error) {
 		sf := v.Type().Field(i)
 		value, ok := sf.Tag.Lookup("env")
 		if !ok {
-			// skip fields without the `env` tag.
-			continue
+			continue // skip fields without the `env` tag.
 		}
 
 		parts := strings.Split(value, ",")
@@ -290,9 +263,6 @@ func (l *loader) parseVars(v reflect.Value) ([]Var, error) {
 	return vars, nil
 }
 
-// lookupEnv retrieves the value of the environment variable named by the key
-// using the internal [Provider]. It replaces $VAR or ${VAR} in the result
-// using [os.Expand] if expand is true.
 func (l *loader) lookupEnv(key string, expand bool) (string, bool) {
 	value, ok := l.provider.LookupEnv(key)
 	if !ok {

env_test.go

@@ -172,7 +172,6 @@ func TestLoadFrom(t *testing.T) {
 	})
 
 	t.Run("with usage on error", func(t *testing.T) {
-		// reset to the default usage after the test is finished.
 		usage := env.Usage
 		defer func() { env.Usage = usage }()
 
@@ -289,8 +288,8 @@ func TestLoadFrom(t *testing.T) {
 	t.Run("parsing errors", func(t *testing.T) {
 		test := func(name, envName string, checkErr func(error) bool) {
 			t.Run(name, func(t *testing.T) {
-				// "-" is an invalid value for all these types, will cause an
-				// error for strconv.Parse*, time.ParseDuration and net.ParseIP.
+				// "-" is an invalid value for all the following types,
+				// it causes an error for strconv.Parse*, time.ParseDuration and net.ParseIP.
 				m := env.Map{envName: "-"}
 
 				var cfg struct {
@@ -311,7 +310,6 @@ func TestLoadFrom(t *testing.T) {
 			return errors.Is(err, strconv.ErrSyntax)
 		}
 		isInvalidDuration := func(err error) bool {
-			// time.ParseDuration does not return any sentinel error :(
 			return errors.Unwrap(err).Error() == `time: invalid duration "-"`
 		}
 		asParseError := func(err error) bool {

provider.go

@@ -4,12 +4,12 @@ import "os"
 
 // Provider represents an entity that is able to provide environment variables.
 type Provider interface {
-	// LookupEnv retrieves the value of the environment variable named by the
-	// key. If it is not found, the boolean will be false.
+	// LookupEnv retrieves the value of the environment variable named by the key.
+	// If it is not found, the boolean will be false.
 	LookupEnv(key string) (value string, ok bool)
 }
 
-// ProviderFunc is an adapter that allows using functions as [Provider].
+// ProviderFunc is an adapter that allows using a function as [Provider].
 type ProviderFunc func(key string) (value string, ok bool)
 
 // LookupEnv implements the [Provider] interface.
@@ -27,16 +27,12 @@ func (m Map) LookupEnv(key string) (string, bool) {
 	return value, ok
 }
 
-// MultiProvider combines multiple providers into a single one, which will
-// contain the union of their environment variables. The order of the given
-// providers matters: if the same key is found in several providers, the value
-// from the last one takes precedence.
+// MultiProvider combines multiple providers into a single one containing the union of all environment variables.
+// The order of the given providers matters: if the same key occurs more than once, the later value takes precedence.
 func MultiProvider(ps ...Provider) Provider { return providers(ps) }
 
-// providers wraps a slice of providers so it can be used as [Provider].
 type providers []Provider
 
-// LookupEnv implements the [Provider] interface.
 func (ps providers) LookupEnv(key string) (string, bool) {
 	var value string
 	var found bool

provider_test.go

@@ -59,7 +59,7 @@ func TestMultiProvider(t *testing.T) {
 		"BAR": "2",
 	}
 	m2 := env.Map{
-		"BAR": "3", // overrides BAR from m1
+		"BAR": "3", // overrides BAR from m1.
 		"BAZ": "4",
 	}
 	p := env.MultiProvider(m1, m2)

reflect.go

@@ -33,8 +33,7 @@ func kindOf(v reflect.Value, kinds ...reflect.Kind) bool {
 	return false
 }
 
-// implements reports whether v's type implements one of the provided
-// interfaces.
+// implements reports whether v's type implements one of the provided interfaces.
 func implements(v reflect.Value, ifaces ...reflect.Type) bool {
 	for _, iface := range ifaces {
 		if t := v.Type(); t.Implements(iface) || reflect.PtrTo(v.Type()).Implements(iface) {
@@ -49,8 +48,7 @@ func structPtr(v reflect.Value) bool {
 	return v.IsValid() && v.Kind() == reflect.Ptr && v.Elem().Kind() == reflect.Struct && !v.IsNil()
 }
 
-// setValue parses s based on v's type/kind and sets v's underlying value to the
-// result.
+// setValue parses s based on v's type/kind and sets v's underlying value to the result.
 func setValue(v reflect.Value, s string) error {
 	switch {
 	case typeOf(v, durationType):
@@ -72,7 +70,6 @@ func setValue(v reflect.Value, s string) error {
 	}
 }
 
-// setInt parses an int value from s and sets v's underlying value to it.
 func setInt(v reflect.Value, s string) error {
 	bits := v.Type().Bits()
 	i, err := strconv.ParseInt(s, 10, bits)
@@ -83,7 +80,6 @@ func setInt(v reflect.Value, s string) error {
 	return nil
 }
 
-// setUint parses an uint value from s and sets v's underlying value to it.
 func setUint(v reflect.Value, s string) error {
 	bits := v.Type().Bits()
 	u, err := strconv.ParseUint(s, 10, bits)
@@ -94,7 +90,6 @@ func setUint(v reflect.Value, s string) error {
 	return nil
 }
 
-// setFloat parses a float value from s and sets v's underlying value to it.
 func setFloat(v reflect.Value, s string) error {
 	bits := v.Type().Bits()
 	f, err := strconv.ParseFloat(s, bits)
@@ -105,7 +100,6 @@ func setFloat(v reflect.Value, s string) error {
 	return nil
 }
 
-// setBool parses a bool value from s and sets v's underlying value to it.
 func setBool(v reflect.Value, s string) error {
 	b, err := strconv.ParseBool(s)
 	if err != nil {
@@ -115,14 +109,11 @@ func setBool(v reflect.Value, s string) error {
 	return nil
 }
 
-// setString sets v's underlying value to s.
 func setString(v reflect.Value, s string) error {
 	v.SetString(s)
 	return nil
 }
 
-// setDuration parses a duration value from s and sets v's underlying value to
-// it.
 func setDuration(v reflect.Value, s string) error {
 	d, err := time.ParseDuration(s)
 	if err != nil {
@@ -132,7 +123,6 @@ func setDuration(v reflect.Value, s string) error {
 	return nil
 }
 
-// setUnmarshaler calls v's UnmarshalText method with s as the text argument.
 func setUnmarshaler(v reflect.Value, s string) error {
 	u := v.Addr().Interface().(encoding.TextUnmarshaler)
 	if err := u.UnmarshalText([]byte(s)); err != nil {
@@ -141,8 +131,6 @@ func setUnmarshaler(v reflect.Value, s string) error {
 	return nil
 }
 
-// setSlice creates a new slice of the values parsed from s and sets v's
-// underlying value to it.
 func setSlice(v reflect.Value, s []string) error {
 	slice := reflect.MakeSlice(v.Type(), len(s), cap(s))
 	for i := 0; i < slice.Len(); i++ {