Add docs, improve README

Makefile

@@ -10,10 +10,10 @@ GO_FORMATTER := gofumpt
 IS_GNU_SED := $(shell sed --version >/dev/null 2>&1 && echo true || echo false)
 SED_INLINE := $(if $(filter true,$(IS_GNU_SED)),-i,-i '')
 
-.PHONY: all tools schema generate test build install clean
+.PHONY: all tools schema generate test build install docs clean
 
 # Default target
-all: tools schema generate test build install
+all: tools schema generate test build docs install
 
 tools:
 	go install golang.org/x/tools/cmd/stringer
@@ -56,6 +56,9 @@ build: generate test
 install:
 	go install -v $(CLIENT_PKG)
 
+docs:
+	bin/eia-client docs md
+
 # Clean up generated files and build artifacts
 clean:
 	rm -rf bin/eia-client

README.md

@@ -1,3 +1,72 @@
 # eia-api-go
 
 A go package for interacting with the EIA API v2
+
+A client binary for interacting with the EIA API v2
+
+[EIA API Documentation](https://www.eia.gov/opendata/documentation.php)
+
+## EIA Package
+
+The EIA client wrapper at
+gitea.libretechconsulting.com/rmcguire/eia-api-go/pkg/eia provides a functional
+set of tools for common EIA API endpoints, and loads in generated endpoints with
+a client wrapper with auth middleware.
+
+To create a new client, be sure to pass in opts.APIKey.
+
+```go
+client, err := eia.NewClient(&eia.ClientOpts{
+    Context:  context.Background(),
+    APIKey:   os.Getenv("EIA_API_KEY"),
+    LogLevel: os.Getenv("EIA_API_LOG_LEVEL"),
+})
+if err != nil {
+    panic(err)
+}
+```
+
+Client code is autogenerated from the published swagger spec (see "Download YAML
+File" link on EIA website), and a number of corrections have been made. The
+swagger spec claims many fields are int, float, etc.. but every single field
+I've see has been a quoted string. This and other issues with their spec
+required correction, which you can see in the `sed` commands in the
+[Makefile](Makefile).
+
+## EIA Client Binary
+
+A helper tool has been created to make it easier to explore routes and facets,
+something the API spec alone doesn't help with. It requires at minimum an API
+key in environment at EIA_API_KEY.
+
+[EIA Client Documentation](docs/eia-client.md)
+
+```
+Useful utilities for EIA API v2
+
+Usage:
+  eia-client [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  get         Commands for getting metadata
+  help        Help about any command
+  list        Commands for listing metadata
+
+Flags:
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -h, --help                 help for eia-client
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+
+Use "eia-client [command] --help" for more information about a command.
+```
+
+### Installing
+
+`go install -v
+gitea.libretechconsulting.com/rmcguire/eia-api-go/cmd/eia-client@latest`
+
+It is strongly suggested to load autocomplete funcs. For zsh, you could add
+something like `source <(eia-client completion zsh)` to your zshrc/omz, etc..

TODO.md

@@ -1,10 +1,15 @@
 # EIA API GO TODO
 
+## Distribution
+
+- [x] Add Gitea CI
+- [x] Add Docs
+
 ## EIA Package
 
 - [x] Make reflection match a STRING type instead of the underlying type
 - [x] Move cmd/eia-client/internal/util/util_reflect to pkg/eia
-- [x] Figure out how the fuck to support multiple facets in this piece of shit fucking API spec. Seriously, amateur bullshit.
+- [x] Figure out multiple facets, api is challenging with generated code
 
 ## EIA Client Tool
 

cmd/eia-client/cmd/docs/docs.go

@@ -0,0 +1,58 @@
+package docs
+
+import (
+	"os"
+
+	"gitea.libretechconsulting.com/rmcguire/eia-api-go/cmd/eia-client/internal/util"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+var DocsCmd = &cobra.Command{
+	Use:       "docs",
+	Aliases:   []string{"documentation"},
+	Short:     "Generate documentation for eia-client",
+	Args:      cobra.RangeArgs(1, 1),
+	ValidArgs: []string{"md", "man", "yaml"},
+	Run:       runDocsCmd,
+}
+
+func runDocsCmd(cmd *cobra.Command, args []string) {
+	outDir, err := cmd.Flags().GetString(util.FLAG_OUTPUT_DIR)
+	if err != nil {
+		util.Logger(cmd).Fatal().Err(err).Send()
+	}
+
+	prepareDocsDir(cmd, outDir)
+
+	switch args[0] {
+	case "md":
+		err = doc.GenMarkdownTree(cmd.Root(), outDir)
+	case "man":
+		err = doc.GenManTree(cmd.Root(), &doc.GenManHeader{
+			Title:   "EIA Client",
+			Section: "1",
+		}, outDir)
+	case "yaml":
+		err = doc.GenYamlTree(cmd.Root(), outDir)
+	default:
+		util.Logger(cmd).Fatal().Str("docType", args[0]).Msg("invalid doc type given")
+	}
+
+	util.Logger(cmd).Info().Err(err).Msg("doc generation complete")
+}
+
+func prepareDocsDir(cmd *cobra.Command, outDir string) {
+	_, err := os.Stat(outDir)
+	if err != nil {
+		err = os.Mkdir(outDir, 0o755)
+		if err != nil {
+			util.Logger(cmd).Fatal().Err(err).Str("outdir", outDir).
+				Msg("unable to prepare output directory")
+		}
+	}
+}
+
+func init() {
+	DocsCmd.PersistentFlags().StringP(util.FLAG_OUTPUT_DIR, "o", "./docs", "specify output directory for documentation")
+}

cmd/eia-client/cmd/root.go

@@ -31,6 +31,7 @@ import (
 	"github.com/rs/zerolog"
 	"github.com/spf13/cobra"
 
+	"gitea.libretechconsulting.com/rmcguire/eia-api-go/cmd/eia-client/cmd/docs"
 	"gitea.libretechconsulting.com/rmcguire/eia-api-go/cmd/eia-client/cmd/get"
 	"gitea.libretechconsulting.com/rmcguire/eia-api-go/cmd/eia-client/cmd/list"
 	"gitea.libretechconsulting.com/rmcguire/eia-api-go/cmd/eia-client/internal/util"
@@ -98,4 +99,5 @@ func init() {
 	// Subcommands
 	rootCmd.AddCommand(list.ListCmd)
 	rootCmd.AddCommand(get.GetCmd)
+	rootCmd.AddCommand(docs.DocsCmd)
 }

cmd/eia-client/internal/util/util.go

@@ -15,6 +15,8 @@ const (
 
 	FLAG_LOG_LEVEL = "logLevel"
 	ENV_LOG_LEVEL  = "LOG_LEVEL"
+
+	FLAG_OUTPUT_DIR = "outdir"
 )
 
 // Type for context data

docs/eia-client.md

@@ -0,0 +1,22 @@
+## eia-client
+
+Useful utilities for EIA API v2
+
+### Options
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -h, --help                 help for eia-client
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client completion](eia-client_completion.md)	 - Generate the autocompletion script for the specified shell
+* [eia-client docs](eia-client_docs.md)	 - Generate documentation for eia-client
+* [eia-client get](eia-client_get.md)	 - Commands for getting metadata
+* [eia-client list](eia-client_list.md)	 - Commands for listing metadata
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_completion.md

@@ -0,0 +1,34 @@
+## eia-client completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for eia-client for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client](eia-client.md)	 - Useful utilities for EIA API v2
+* [eia-client completion bash](eia-client_completion_bash.md)	 - Generate the autocompletion script for bash
+* [eia-client completion fish](eia-client_completion_fish.md)	 - Generate the autocompletion script for fish
+* [eia-client completion powershell](eia-client_completion_powershell.md)	 - Generate the autocompletion script for powershell
+* [eia-client completion zsh](eia-client_completion_zsh.md)	 - Generate the autocompletion script for zsh
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_completion_bash.md

@@ -0,0 +1,53 @@
+## eia-client completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(eia-client completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	eia-client completion bash > /etc/bash_completion.d/eia-client
+
+#### macOS:
+
+	eia-client completion bash > $(brew --prefix)/etc/bash_completion.d/eia-client
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+eia-client completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client completion](eia-client_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_completion_fish.md

@@ -0,0 +1,44 @@
+## eia-client completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	eia-client completion fish | source
+
+To load completions for every new session, execute once:
+
+	eia-client completion fish > ~/.config/fish/completions/eia-client.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+eia-client completion fish [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client completion](eia-client_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_completion_powershell.md

@@ -0,0 +1,41 @@
+## eia-client completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	eia-client completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+eia-client completion powershell [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for powershell
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client completion](eia-client_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_completion_zsh.md

@@ -0,0 +1,55 @@
+## eia-client completion zsh
+
+Generate the autocompletion script for zsh
+
+### Synopsis
+
+Generate the autocompletion script for the zsh shell.
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+	echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions in your current shell session:
+
+	source <(eia-client completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	eia-client completion zsh > "${fpath[1]}/_eia-client"
+
+#### macOS:
+
+	eia-client completion zsh > $(brew --prefix)/share/zsh/site-functions/_eia-client
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+eia-client completion zsh [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for zsh
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client completion](eia-client_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_docs.md

@@ -0,0 +1,29 @@
+## eia-client docs
+
+Generate documentation for eia-client
+
+```
+eia-client docs [flags]
+```
+
+### Options
+
+```
+  -h, --help            help for docs
+  -o, --outdir string   specify output directory for documentation (default "./docs")
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client](eia-client.md)	 - Useful utilities for EIA API v2
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_get.md

@@ -0,0 +1,26 @@
+## eia-client get
+
+Commands for getting metadata
+
+### Options
+
+```
+  -h, --help   help for get
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client](eia-client.md)	 - Useful utilities for EIA API v2
+* [eia-client get facet](eia-client_get_facet.md)	 - Describe facet for given API route
+* [eia-client get route](eia-client_get_route.md)	 - Describe a route
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_get_facet.md

@@ -0,0 +1,28 @@
+## eia-client get facet
+
+Describe facet for given API route
+
+```
+eia-client get facet route facet [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for facet
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client get](eia-client_get.md)	 - Commands for getting metadata
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_get_route.md

@@ -0,0 +1,28 @@
+## eia-client get route
+
+Describe a route
+
+```
+eia-client get route [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for route
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client get](eia-client_get.md)	 - Commands for getting metadata
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_list.md

@@ -0,0 +1,26 @@
+## eia-client list
+
+Commands for listing metadata
+
+### Options
+
+```
+  -h, --help   help for list
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client](eia-client.md)	 - Useful utilities for EIA API v2
+* [eia-client list facets](eia-client_list_facets.md)	 - List facets for given API route
+* [eia-client list routes](eia-client_list_routes.md)	 - List routes, optionally by type (default is Data)
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_list_facets.md

@@ -0,0 +1,28 @@
+## eia-client list facets
+
+List facets for given API route
+
+```
+eia-client list facets route [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for facets
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client list](eia-client_list.md)	 - Commands for listing metadata
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

docs/eia-client_list_routes.md

@@ -0,0 +1,31 @@
+## eia-client list routes
+
+List routes, optionally by type (default is Data)
+
+```
+eia-client list routes [flags]
+```
+
+### Options
+
+```
+  -a, --all                  List all methods, no filtering
+  -f, --filters strings      Optional [inclusion] filters, case insensitive
+  -h, --help                 help for routes
+  -p, --routePrefix string   Prefix for routes, ignore with -a flag (default "Get")
+```
+
+### Options inherited from parent commands
+
+```
+      --apiKey string        API Key, or set EIA_API_KEY in environment
+  -L, --apiLogLevel string   Log Level for EIA API Middleware, or set EIA_API_LOG_LEVEL in environment
+  -l, --logLevel string      Log Level, or set LOG_LEVEL in environment
+  -t, --timeout duration     Request timeout, or set EIA_API_TMOUT in environment (default 15s)
+```
+
+### SEE ALSO
+
+* [eia-client list](eia-client_list.md)	 - Commands for listing metadata
+
+###### Auto generated by spf13/cobra on 17-Dec-2024

go.mod

@@ -18,6 +18,7 @@ require (
 
 require (
 	github.com/apapsch/go-jsonmerge/v2 v2.0.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
 	github.com/dprotaso/go-yit v0.0.0-20240618133044-5a0af90af097 // indirect
 	github.com/getkin/kin-openapi v0.128.0 // indirect
 	github.com/go-openapi/jsonpointer v0.21.0 // indirect
@@ -32,6 +33,7 @@ require (
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mohae/deepcopy v0.0.0-20170929034955-c48cc78d4826 // indirect
 	github.com/perimeterx/marshmallow v1.1.5 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/speakeasy-api/openapi-overlay v0.9.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/vmware-labs/yaml-jsonpath v0.3.2 // indirect

go.sum

@@ -6,6 +6,7 @@ github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWR
 github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
 github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
 github.com/coreos/go-systemd/v22 v22.5.0/go.mod h1:Y58oyj3AT4RCenI/lSvhwexgC+NSVTIJ3seZv2GcEnc=
+github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
@@ -110,6 +111,7 @@ github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99
 github.com/rs/xid v1.5.0/go.mod h1:trrq9SKmegXys3aeAKXMUTdJsYXVwGY3RLcfgqegfbg=
 github.com/rs/zerolog v1.33.0 h1:1cU2KZkvPxNyfgEmhHAz/1A9Bz+llsdYzklWFzgp0r8=
 github.com/rs/zerolog v1.33.0/go.mod h1:/7mN4D5sKwJLZQ2b/znpjC3/GQWY/xaDXUM0kKWRHss=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/sergi/go-diff v1.1.0 h1:we8PVUC3FE2uYfodKH/nBHMSetSfHDR6scGdBi+erh0=
 github.com/sergi/go-diff v1.1.0/go.mod h1:STckp+ISIX8hZLjrqAeVduY0gWCT9IjLuqbuNXdaHfM=

pkg/eia/eia.go

@@ -1,3 +1,6 @@
+// Simple wrapper around generated EIA API client
+// that embeds a client with a bearer auth interceptor
+// and optional logging middleware
 package eia
 
 import (
@@ -21,13 +24,8 @@ const (
 	defaultLogLevel    = zerolog.DebugLevel
 )
 
-// Simple wrapper around generated EIA API client
+// Both marshalled and raw response methods
-// that embeds a client with a bearer auth interceptor
+// loaded into client
-// and optional logging middleware
-//
-// Performs a basic availability check against the API
-// when creating a new client, and exposes a Ping() method
-// for health / readiness probes
 type Client struct {
 	ctx                context.Context
 	apiKey             string
@@ -36,6 +34,7 @@ type Client struct {
 	*eiaapi.ClientWithResponses
 }
 
+// APIKey is mandatory for interacting with the EIA API
 type ClientOpts struct {
 	Context            context.Context // Base context for requests
 	APIKey             string          // API Key [EIA Opendata API v2](https://www.eia.gov/opendata/index.php)
@@ -65,6 +64,9 @@ func NewFacets(facets ...*Facet) *eiaapi.Facets {
 	return &newFacets
 }
 
+// Creates a new EIA API client with auth and logging middleware,
+// as well as both marshalled and raw client funcs.
+// Be sure to pass in an API Key in opts.APIKey.
 func NewClient(opts *ClientOpts) (*Client, error) {
 	baseURL := defaultBaseURL
 	if opts.BaseURL != nil {
@@ -85,14 +87,6 @@ func NewClient(opts *ClientOpts) (*Client, error) {
 
 	middlewares := make([]eiaapi.ClientOption, 0, 2)
 
-	// Injects Authorization: Bearer <APIKey> header into
-	// outbound API calls
-	// basicAuth, err := securityprovider.NewSecurityProviderBearerToken(opts.APIKey)
-	// if err != nil {
-	// 	return nil, err
-	// }
-	// middlewares = append(middlewares, eiaapi.WithRequestEditorFn(basicAuth.Intercept))
-
 	// Injects API key as query parameter: ?api_key=<apiKey>
 	paramAuth, err := securityprovider.NewSecurityProviderApiKey("query", "api_key", opts.APIKey)
 	if err != nil {