config: Rename Package to PackageConfig, add docs (#84)

Renames the Package struct to PackageConfig
to make it clear that it is a configuration struct.

This differentiation will help disconnect
the configuration-level representation
from the runtime representation of this information.

This patch also adds documentation to the config package
that was previously missing.

1 files changed, 40 insertions, 11 deletions

diff --git a/config.go b/config.go
index 95dad7a..4d60a36 100644
--- a/config.go
+++ b/config.go
@@ -12,22 +12,51 @@ const (
 	_defaultBranch      = "master"
 )
 
-// Config represents the structure of the yaml file
+// Config defines the configuration for a Sally server.
 type Config struct {
-	URL      string             `yaml:"url"`
-	Packages map[string]Package `yaml:"packages"`
-	Godoc    struct {
-		Host string `yaml:"host"`
-	} `yaml:"godoc"`
+	// URL is the base URL for all vanity imports.
+	URL string `yaml:"url"` // required
+
+	// Packages is a map of package name to package details.
+	Packages map[string]PackageConfig `yaml:"packages"`
+
+	// Godoc specifies where to redirect to for documentation.
+	Godoc GodocConfig `yaml:"godoc"`
+}
+
+// GodocConfig is the configuration for the documentation server.
+type GodocConfig struct {
+	// Host is the hostname of the documentation server.
+	//
+	// Defaults to pkg.go.dev.
+	Host string `yaml:"host"`
 }
 
-// Package details the options available for each repo
-type Package struct {
-	Repo   string `yaml:"repo"`
+// PackageConfig is the configuration for a single Go module
+// that is served by Sally.
+type PackageConfig struct {
+	// Repo is the URL to the Git repository for the module
+	// without the https:// prefix.
+	// This URL must serve the Git HTTPS protocol.
+	//
+	// For example, "github.com/uber-go/sally".
+	Repo string `yaml:"repo"` // required
+
+	// Branch is the default branch for the repository
+	// when no version is specified.
+	//
+	// Defaults to master.
 	Branch string `yaml:"branch"`
-	URL    string `yaml:"url"`
+	// NB: This is no longer necessary.
+	// https://github.com/uber-go/sally/issues/83
+
+	// URL is the base URL of the vanity import for this module.
+	//
+	// Defaults to the URL specified in the top-level config.
+	URL string `yaml:"url"`
 
-	Desc string `yaml:"description"` // plain text only
+	// Desc is a plain text description of this module.
+	Desc string `yaml:"description"`
 }
 
 // Parse takes a path to a yaml file and produces a parsed Config