Add comments to most exported functions/types

pkg/cache/schemacache.go

@@ -7,21 +7,26 @@ import (
 	"github.com/xeipuuv/gojsonschema"
 )
 
+// SchemaCache is a cache for downloaded schemas, so each file is only retrieved once
 type SchemaCache struct {
 	sync.RWMutex
 	schemas map[string]*gojsonschema.Schema
 }
 
+// New creates a new cache for downloaded schemas
 func New() *SchemaCache {
 	return &SchemaCache{
 		schemas: map[string]*gojsonschema.Schema{},
 	}
 }
 
+// Key computes a key for a specific JSON schema from its Kind, the resource API Version, and the
+// Kubernetes version
 func Key(resourceKind, resourceAPIVersion, k8sVersion string) string {
 	return fmt.Sprintf("%s-%s-%s", resourceKind, resourceAPIVersion, k8sVersion)
 }
 
+// Get retrieves the JSON schema given a resource signature
 func (c *SchemaCache) Get(key string) (*gojsonschema.Schema, bool) {
 	c.RLock()
 	defer c.RUnlock()
@@ -29,6 +34,7 @@ func (c *SchemaCache) Get(key string) (*gojsonschema.Schema, bool) {
 	return schema, ok
 }
 
+// Set adds a JSON schema to the schema cache
 func (c *SchemaCache) Set(key string, schema *gojsonschema.Schema) {
 	c.Lock()
 	defer c.Unlock()

pkg/config/config.go

@@ -50,6 +50,7 @@ func splitCSV(csvStr string) map[string]bool {
 	return valuesMap
 }
 
+// FromFlags retrieves kubeconform's runtime configuration from the command-line parameters
 func FromFlags(progName string, args []string) (Config, string, error) {
 	var schemaLocationsParam, ignoreFilenamePatterns arrayParam
 	var skipKindsCSV, rejectKindsCSV string

pkg/registry/http.go

@@ -8,12 +8,14 @@ import (
 	"time"
 )
 
-type KubernetesRegistry struct {
+// SchemaRegistry is a file repository (local or remote) that contains JSON schemas for Kubernetes resources
+type SchemaRegistry struct {
 	c                  *http.Client
 	schemaPathTemplate string
 	strict             bool
 }
 
+// NotFoundError is returned when the registry does not contain a schema for the resource
 type NotFoundError struct {
 	err error
 }
@@ -23,7 +25,7 @@ func newNetFoundError(err error) *NotFoundError {
 }
 func (e *NotFoundError) Error() string { return e.err.Error() }
 
-func newHTTPRegistry(schemaPathTemplate string, strict bool, skipTLS bool) *KubernetesRegistry {
+func newHTTPRegistry(schemaPathTemplate string, strict bool, skipTLS bool) *SchemaRegistry {
 	reghttp := &http.Transport{
 		MaxIdleConns:       100,
 		IdleConnTimeout:    3 * time.Second,
@@ -34,14 +36,15 @@ func newHTTPRegistry(schemaPathTemplate string, strict bool, skipTLS bool) *Kube
 		reghttp.TLSClientConfig = &tls.Config{InsecureSkipVerify: true}
 	}
 
-	return &KubernetesRegistry{
+	return &SchemaRegistry{
 		c:                  &http.Client{Transport: reghttp},
 		schemaPathTemplate: schemaPathTemplate,
 		strict:             strict,
 	}
 }
 
-func (r KubernetesRegistry) DownloadSchema(resourceKind, resourceAPIVersion, k8sVersion string) ([]byte, error) {
+// DownloadSchema downloads the schema for a particular resource from an HTTP server
+func (r SchemaRegistry) DownloadSchema(resourceKind, resourceAPIVersion, k8sVersion string) ([]byte, error) {
 	url, err := schemaPath(r.schemaPathTemplate, resourceKind, resourceAPIVersion, k8sVersion, r.strict)
 	if err != nil {
 		return nil, err

pkg/resource/resource.go

@@ -4,16 +4,19 @@ import (
 	"sigs.k8s.io/yaml"
 )
 
+// Resource represents a Kubernetes resource within a file
 type Resource struct {
 	Path  string
 	Bytes []byte
 	sig   *Signature
 }
 
+// Signature is a key representing a Kubernetes resource
 type Signature struct {
 	Kind, Version, Namespace, Name string
 }
 
+// Signature computes a signature for a resource, based on its Kind, Version, Namespace & Name
 func (res *Resource) Signature() (*Signature, error) {
 	if res.sig != nil {
 		return res.sig, nil

pkg/resource/stream.go

@@ -7,6 +7,7 @@ import (
 	"io/ioutil"
 )
 
+// FromStream reads resources from a byte stream, usually here stdin
 func FromStream(ctx context.Context, path string, r io.Reader) (<-chan Resource, <-chan error) {
 	resources := make(chan Resource)
 	errors := make(chan error)

pkg/validator/validator.go

@@ -37,12 +37,14 @@ func (f ValidFormat) IsFormat(input interface{}) bool {
 // 	gojsonschema.FormatCheckers.Add("int-or-string", ValidFormat{})
 // }
 
+// Result contains the details of the result of a resource validation
 type Result struct {
 	Resource resource.Resource
 	Err      error
 	Status   Status
 }
 
+// NewError is a utility function to generate a validation error
 func NewError(filename string, err error) Result {
 	return Result{
 		Resource: resource.Resource{Path: filename},