Document all exported types, functions and variables.

cmd/jiralert/main.go

@@ -22,6 +22,7 @@ var (
 	listenAddress = flag.String("listen-address", ":9097", "The address to listen on for HTTP requests.")
 	configFile    = flag.String("config", "config/jiralert.yml", "The JIRAlert configuration file")
 
+	// Build version, set by make to latest git tag via `-ldflags "-X main.Version=$(VERSION)"`.
 	Version = "<local build>"
 )
 

config.go

@@ -70,6 +70,8 @@ func resolveFilepaths(baseDir string, cfg *Config) {
 	cfg.Template = join(cfg.Template)
 }
 
+// ReceiverConfig is the configuration for one receiver. It has a unique name and includes API access fields (URL, user
+// and password) and issue fields (required -- e.g. project, issue type -- and optional -- e.g. priority).
 type ReceiverConfig struct {
 	Name string `yaml:"name" json:"name"`
 

notify.go

@@ -13,12 +13,14 @@ import (
 	"github.com/trivago/tgo/tcontainer"
 )
 
+// Receiver wraps a JIRA client corresponding to a specific Alertmanager receiver, with its configuration and templates.
 type Receiver struct {
 	conf   *ReceiverConfig
 	tmpl   *Template
 	client *jira.Client
 }
 
+// NewReceiver creates a Receiver using the provided configuration and template.
 func NewReceiver(c *ReceiverConfig, t *Template) (*Receiver, error) {
 	client, err := jira.NewClient(http.DefaultClient, c.APIURL)
 	if err != nil {

template.go

@@ -9,6 +9,8 @@ import (
 	log "github.com/golang/glog"
 )
 
+// Template wraps a text template and error, to make it easier to execute multiple templates and only check for errors
+// once at the end (assuming one is only interested in the first error, which is usually the case).
 type Template struct {
 	tmpl *template.Template
 	err  error
@@ -29,6 +31,7 @@ var funcs = template.FuncMap{
 	},
 }
 
+// LoadTemplate reads and parses all templates defined in the given file and constructs a jiralert.Template.
 func LoadTemplate(path string) (*Template, error) {
 	log.V(1).Infof("Loading templates from %q", path)
 	tmpl, err := template.New("").Option("missingkey=zero").Funcs(funcs).ParseFiles(path)
@@ -38,6 +41,9 @@ func LoadTemplate(path string) (*Template, error) {
 	return &Template{tmpl: tmpl}, nil
 }
 
+// Execute parses the provided text (or returns it unchanged if not a Go template), associates it with the templates
+// defined in t.tmpl (so they may be referenced and used) and applies the resulting template to the specified data
+// object, returning the output as a string.
 func (t *Template) Execute(text string, data interface{}) string {
 	log.V(2).Infof("Executing template %q...", text)
 	if !strings.Contains(text, "{{") {