Update docs

decode.go

@@ -36,6 +36,7 @@ type DecodeOptions struct {
 	ReplaceVars bool
 }
 
+// A Decoder looks up environment variables while decoding them into a struct.
 type Decoder struct {
 	DecodeOptions
 	TagOptions
@@ -45,8 +46,8 @@ type Decoder struct {
 
 const panicNilLookupper = "env.Decoder: Lookupper must not be nil"
 
-// NewDecoder returns a new Decoder that looks up environment variables from
-// any Lookupper.
+// NewDecoder returns a new Decoder which looks up environment variables from
+// the provided Lookupper(s). When a Chain is provided it must not be empty.
 func NewDecoder(src ...Lookupper) *Decoder {
 	l, chained := chain(src...)
 	if !chained && l == nil {
@@ -74,7 +75,7 @@ func (d *Decoder) Strict() *Decoder {
 	return d
 }
 
-// WithLookupper changes the Decoder's internal Lookupper to l.
+// WithLookupper changes the internal Lookupper to l.
 func (d *Decoder) WithLookupper(l Lookupper) *Decoder {
 	if l == nil {
 		panic(panicNilLookupper)
@@ -84,11 +85,13 @@ func (d *Decoder) WithLookupper(l Lookupper) *Decoder {
 	return d
 }
 
+// WithOptions changes the internal DecodeOptions to opts.
 func (d *Decoder) WithOptions(opts DecodeOptions) *Decoder {
 	d.DecodeOptions = opts
 	return d
 }
 
+// WithTagOptions changes the internal TagOptions to opts.
 func (d *Decoder) WithTagOptions(opts TagOptions) *Decoder {
 	d.TagOptions = opts
 	return d

doc.go

@@ -4,9 +4,13 @@
 
 /*
 Package env implements encoding and decoding of environment variables from
-files, the OS or other data sources. It supports unmarshalling to structs and
-maps. The mapping between environment variables and Go values is described in
-the documentation for the Marshal and Unmarshal functions.
+files, the OS or other io.Reader compatible data sources. It supports
+unmarshalling to structs and maps, and marshaling from various types to files
+and io.Writer. It can also be used to load/overload environment variables into
+the system.
+
+The mapping between environment variables and Go values is described in the
+documentation for the Marshal and Unmarshal functions.
 
 # Supported types
 
@@ -24,7 +28,8 @@ variables are replaced before being set to the system using Setenv.
 # Dotenv
 
 The dotenv package supports reading and loading environment variables from .env
-files based on active environment (e.g. prod, dev etc.).
+files based on active environment (e.g. prod, dev etc.). See its documentation
+for more information.
 
 # Writing
 

dotenv/doc.go

@@ -0,0 +1,17 @@
+// Copyright (c) 2022, Roel Schut. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+/*
+Package dotenv supports reading and loading environment variables from .env
+files based on active environment (e.g. prod, dev etc.). The order or reading
+is as follows:
+- .env
+- .env.local
+- .env.{active-env}
+- .env.{active-env}.local
+
+It is recommended to not commit any .local files to the repository as these
+represent variables that are specific to your local environment.
+*/
+package dotenv

dotenv/read.go

@@ -21,23 +21,27 @@ var (
 	_ io.Closer                = (*Reader)(nil)
 )
 
+// A Reader reads .env files from a filesystem and provides the mechanism to
+// lookup environment variables. Its zero value is ready to use and reads from
+// the current working directory.
 type Reader struct {
 	fsys  fs.FS
 	dir   string
 	files []*file
 	found env.Map
 }
 
-// Read reads .env files from dir depending on the provided ActiveEnvironment.
+// Read reads .env files from dir, depending on the provided ActiveEnvironment.
 //
 //	var cfg MyConfig
 //	dec := env.NewDecoder(dotenv.Read("./", dotenv.Development))
 //	dec.Decode(&cfg)
 func Read(dir string, ae ActiveEnvironment) *Reader {
-	return newReader(osfs.FS{}, dir, ae)
+	return newReader(nil, dir, ae)
 }
 
-// ReadFS reads .env files at dir from fsys.
+// ReadFS reads .env files at dir from fsys, depending on the provided
+// ActiveEnvironment.
 func ReadFS(fsys fs.FS, dir string, ae ActiveEnvironment) *Reader {
 	if fsys == nil {
 		panic(panicNilFsys)
@@ -107,6 +111,7 @@ func (r *Reader) fileReader(f *file) (*envfile.Reader, bool, error) {
 	return f.reader, !f.notExists, nil
 }
 
+// Lookup key by reading from .env files.
 func (r *Reader) Lookup(key string) (env.Value, error) {
 	r.init(nil, "")
 	if v, ok := r.found[key]; ok {
@@ -172,6 +177,7 @@ func (r *Reader) Environ() (env.Map, error) {
 	return res, nil
 }
 
+// Close closes all opened .env files.
 func (r *Reader) Close() error {
 	var err error
 	for _, f := range r.files {

encode.go

@@ -52,27 +52,30 @@ type Encoder struct {
 
 const panicNilWriter = "env.Encoder: io.Writer must not be nil"
 
-// NewEncoder returns a new encoder that writes to w.
+// NewEncoder returns a new Encoder which writes to w.
 func NewEncoder(w io.Writer) *Encoder {
 	var enc Encoder
 	return enc.WithTagOptions(envtag.DefaultOptions()).WithWriter(w)
 }
 
+// WithOptions changes the internal EncodeOptions to opts.
 func (e *Encoder) WithOptions(opts EncodeOptions) *Encoder {
 	e.EncodeOptions = opts
 	return e
 }
 
+// WithTagOptions changes the internal TagOptions to opts.
 func (e *Encoder) WithTagOptions(opts TagOptions) *Encoder {
 	e.TagOptions = opts
 	return e
 }
 
-func (e *Encoder) WithWriter(writer io.Writer) *Encoder {
-	if writer == nil {
+// WithWriter changes the internal io.Writer to w.
+func (e *Encoder) WithWriter(w io.Writer) *Encoder {
+	if w == nil {
 		panic(panicNilWriter)
 	}
-	e.w = writing.ToStringWriter(writer)
+	e.w = writing.ToStringWriter(w)
 	return e
 }
 
@@ -83,7 +86,7 @@ func (e *Encoder) WithWriter(writer io.Writer) *Encoder {
 //   - map[fmt.Stringer]Value
 //   - []NamedValue
 //   - []envtag.Tag
-//   - any valid struct type
+//   - any struct type the rawconv package can handle
 func (e *Encoder) Encode(v any) error {
 	switch src := v.(type) {
 	case Map:

envfile/envfile.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.
 
+// Package envfile provides tools to read and load environment variables from
+// files.
 package envfile
 
 const (