From ae1157f1caa8ca93bdbe1c60f6e5054015e1f009 Mon Sep 17 00:00:00 2001
From: Sam Coe <samcoe@users.noreply.github.com>
Date: Thu, 26 May 2022 14:46:43 +0200
Subject: [PATCH] Add comments

---
 pkg/auth/auth.go     | 14 ++++++++++++++
 pkg/config/config.go | 29 ++++++++++++++++++++++++++++-
 2 files changed, 42 insertions(+), 1 deletion(-)

diff --git a/pkg/auth/auth.go b/pkg/auth/auth.go
index 6939539..f4fc7d7 100644
--- a/pkg/auth/auth.go
+++ b/pkg/auth/auth.go
@@ -1,3 +1,5 @@
+// Package auth is a set of functions for retrieving authentication tokens
+// and authenticated hosts.
 package auth
 
 import (
@@ -19,6 +21,10 @@ const (
 	hostsKey              = "hosts"
 )
 
+// TokenForHost retrieves an authentication token and the source of
+// that token for the specified host. The source can be either an
+// environment variable or the configuration file.
+// Returns blank strings if no applicable token is found.
 func TokenForHost(host string) (string, string) {
 	cfg, _ := config.Read()
 	return tokenForHost(cfg, host)
@@ -51,6 +57,10 @@ func tokenForHost(cfg *config.Config, host string) (string, string) {
 	return "", ""
 }
 
+// KnownHosts retrieves a list of hosts that have corresponding
+// authentication tokens, either from environment variables
+// or the configuration file.
+// Returns an empty string slice if no hosts are found.
 func KnownHosts() []string {
 	cfg, _ := config.Read()
 	return knownHosts(cfg)
@@ -73,6 +83,10 @@ func knownHosts(cfg *config.Config) []string {
 	return hosts.ToSlice()
 }
 
+// DefaultHost retrieves an authenticated host and the source of host.
+// The source can be either an environment variable or the
+// configuration file.
+// Returns "github.com", "default" if no viable host is found.
 func DefaultHost() (string, string) {
 	cfg, _ := config.Read()
 	return defaultHost(cfg)
diff --git a/pkg/config/config.go b/pkg/config/config.go
index e89c60f..f63a2e7 100644
--- a/pkg/config/config.go
+++ b/pkg/config/config.go
@@ -1,5 +1,5 @@
 // Package config is a set of types for interacting with the gh configuration files.
-// Note: This package is intended for use only in `gh`, any other use cases are subject
+// Note: This package is intended for use only in gh, any other use cases are subject
 // to breakage and non-backwards compatible updates.
 package config
 
@@ -22,10 +22,19 @@ const (
 	xdgStateHome  = "XDG_STATE_HOME"
 )
 
+// Config is a in memory representation of the gh configuration files.
+// It can be thought of as map where entries consist of a key that
+// correspond to either a string value or a map value, allowing for
+// multi-level maps.
 type Config struct {
 	entries *yamlmap.Map
 }
 
+// Get a string value from a Config.
+// The keys argument is a sequence of key values so that nested
+// entries can be retrieved. A undefined string will be returned
+// if trying to retrieve a key that corresponds to a map value.
+// Returns "", KeyNotFoundError if any of the keys can not be found.
 func Get(c *Config, keys []string) (string, error) {
 	m := c.entries
 	for _, key := range keys {
@@ -38,6 +47,10 @@ func Get(c *Config, keys []string) (string, error) {
 	return m.Value, nil
 }
 
+// Keys enumerates a Configs keys.
+// The keys argument is a sequence of key values so that nested
+// map values can be have their keys enumerated.
+// Returns nil, KeyNotFoundError if any of the keys can not be found.
 func Keys(c *Config, keys []string) ([]string, error) {
 	m := c.entries
 	for _, key := range keys {
@@ -50,6 +63,11 @@ func Keys(c *Config, keys []string) ([]string, error) {
 	return m.Keys(), nil
 }
 
+// Remove an entry from a Config.
+// The keys argument is a sequence of key values so that nested
+// entries can be removed. Removing an entry that has nested
+// entries removes those also.
+// Returns "", KeyNotFoundError if any of the keys can not be found.
 func Remove(c *Config, keys []string) error {
 	m := c.entries
 	for i := 0; i < len(keys)-1; i++ {
@@ -67,6 +85,10 @@ func Remove(c *Config, keys []string) error {
 	return nil
 }
 
+// Set an string value in a Config.
+// The keys argument is a sequence of key values so that nested
+// entries can be set. If any of the keys do not exist they will
+// be created.
 func Set(c *Config, keys []string, value string) {
 	m := c.entries
 	for i := 0; i < len(keys)-1; i++ {
@@ -81,6 +103,8 @@ func Set(c *Config, keys []string, value string) {
 	m.SetEntry(keys[len(keys)-1], yamlmap.StringValue(value))
 }
 
+// Read gh configuration files from the local file system and
+// return a Config.
 func Read() (*Config, error) {
 	// TODO: Make global config singleton using sync.Once
 	// so as not to read from file every time.
@@ -98,6 +122,9 @@ func ReadFromString(str string) *Config {
 	return &Config{m}
 }
 
+// Write gh configuration files to the local file system.
+// It will only write gh configuration files that have been modified
+// since last being read.
 func Write(config *Config) error {
 	hosts, err := config.entries.FindEntry("hosts")
 	if err == nil && hosts.IsModified() {