Docstring improvements

src/DotEnv.jl

@@ -8,6 +8,9 @@ files into [`ENV`](@ref).  Storing configuration in the environment is based on
 Please don't store secrets in dotenv files, and if you must at least ensure the
 dotenv file(s) are listed in `.gitignore`.
 
+!!! info "API"
+    `DotEnv`: `load!()`, `unload!()`, `config`, `parse`.
+
 # Quickstart
 
 Use `DotEnv.load!()` to load environment variables, `DotEnv.unload!()` to undo
@@ -66,11 +69,27 @@ using PrecompileTools
 
 include("types.jl")
 
+"""
+A list of dotenv file (base)names that should be automatically loaded, from
+least to most authoratative.
+"""
 const ENV_FILENAMES = # From <https://github.com/bkeepers/dotenv>, highest priority last
     [".env",       ".env.production",       ".env.test",       ".env.development",
      ".env.local", ".env.production.local", ".env.test.local", ".env.development.local"]
 
+"""
+The accumulation of dotenv files applied to environment dicts.
+
+This record allows for reasoning of what would happen if a particular
+environment file was never loaded, for example.
+"""
 const ENV_STACKS = IdDict{AbstractDict{String, String}, Vector{EnvFile}}()
+
+"""
+A record of the original values of a particular environment dict.
+
+This is used to record overwritten values, so the original values can be restored later.
+"""
 const ENV_ORIGINALS = IdDict{AbstractDict{String, String}, Dict{String, Union{String, Nothing}}}()
 
 include("parser.jl")

src/loading.jl

@@ -1,3 +1,9 @@
+"""
+    loadexpand!(dotenv::Dict{String, String}, entry::EnvEntry, fallback::AbstractDict{String, String}=ENV)
+
+Modify `dotenv` to incorperate on `entry`, which will be interpolated (if
+appropriate) using `dotenv` and `fallback`.
+"""
 function loadexpand!(dotenv::Dict{String, String}, entry::EnvEntry, fallback::AbstractDict{String, String}=ENV)
     dotenv[entry.key] = if !entry.interpolate || !occursin('$', entry.value)
         entry.value
@@ -16,6 +22,8 @@ expanding interpolated values with `env`.
 
 Should the file `path` exist, an empty `EnvOverlay` is silently returned.
 """
+function config end
+
 function config(entries::Vector{EnvEntry}; env::AbstractDict{String, String} = ENV, override::Bool = false)
     dotenv = Dict{String, String}()
     for entry in entries
@@ -35,14 +43,16 @@ function config(path::AbstractString = ".env"; env::AbstractDict{String, String}
 end
 
 """
-    load!([env=ENV], path::AbstractString = ""; override::Bool=false)
+    load!([env::AbstractDict{String, String}=ENV], path::AbstractString = ""; override::Bool=false)
 
 Load the dotenv file `path`, or should `path` be a directory every
 `ENV_FILENAME` that lies within it, into `env`.
 
 Should `override` be set, values already present in `env` will be replaced with
 statements from the dotenv file(s).
 """
+function load! end
+
 function load!(env::AbstractDict{String, String}, files::Vector{<:AbstractString}; override::Bool=false)
     unload!(env, files)
     for file in files
@@ -92,6 +102,8 @@ Unload the dotenv file `path` from `env`, or should `path` be a directory every
 
 When `env` is omitted, `ENV` is used and a `path` defaults to the current directory.
 """
+function unload! end
+
 function unload!(env::AbstractDict{String, String}, files::Vector{<:AbstractString})
     absfiles = map(abspath, files)
     (!haskey(ENV_STACKS, env) || !any(e -> e.path in absfiles, ENV_STACKS[env])) && return env

src/types.jl

@@ -1,3 +1,8 @@
+"""
+    struct EnvOverlay{B <: AbstractDict{String, String}} <: AbstractDict{String, String}
+
+A wrapper around a base environment dictionary, that overlays new/changed values.
+"""
 struct EnvOverlay{B <: AbstractDict{String, String}} <: AbstractDict{String, String}
     base::B
     overlay::Dict{String, String}
@@ -20,12 +25,28 @@ Base.length(eo::EnvOverlay) = length(eo.overlay)
 Base.iterate(eo::EnvOverlay) = iterate(eo.overlay)
 Base.iterate(eo::EnvOverlay, i) = iterate(eo.overlay, i)
 
+"""
+    struct EnvEntry
+
+A primitive representation of a single entry of a dotenv file.
+
+It is primitive in the sense that the value is untransformed, no interpolation
+has been performed.
+
+See also: `loadexpand!`, `_parse`.
+"""
 struct EnvEntry
     key::String
     value::String
     interpolate::Bool
 end
 
+"""
+    struct EnvFile
+
+A representation of all of the entries in a particular dotenv file, along with
+whether it should overwrite existing values or not.
+"""
 struct EnvFile
     path::String
     entries::Vector{EnvEntry}