lint for proper godoc-style comments (#485)

* lint for proper godoc-style comments

* fix Linux-specific lint error

.golangci.yml

@@ -62,5 +62,13 @@ linters:
     - typecheck
 
 issues:
+  # golangci-lint excludes some stuff we want by default (i.e., proper go-style comments).
+  # We exclude the defaults and then manually exclude the subset of defaults we truly don't
+  # care about.
+  exclude-use-default: false
+
   exclude:
-    - Error return value of .*.Log\x60 is not checked
+    # EXC0001 errcheck: Almost all programs ignore errors on these functions
+    # and in most cases it's ok. This is copied from the golangci-lint defaults
+    # mut modified to include go-kit logging.
+    - Error return value of .((os\.)?std(out|err)\..*|.*Close|.*Flush|os\.Remove(All)?|.*print(f|ln)?|os\.(Un)?Setenv|.*\.Log). is not checked

cmd/agent/agent.go

@@ -16,6 +16,7 @@ import (
 	"github.com/go-kit/kit/log"
 )
 
+// Entrypoint is the entrypoint of the application that starts all subsystems.
 type Entrypoint struct {
 	promMetrics *prom.Agent
 	lokiLogs    *loki.Loki
@@ -24,6 +25,7 @@ type Entrypoint struct {
 	srv         *server.Server
 }
 
+// NewEntryPoint creates a new Entrypoint.
 func NewEntryPoint(logger log.Logger, cfg *config.Config) (*Entrypoint, error) {
 	var (
 		promMetrics *prom.Agent
@@ -91,9 +93,9 @@ func NewEntryPoint(logger log.Logger, cfg *config.Config) (*Entrypoint, error) {
 		manager:     manager,
 		srv:         srv,
 	}, nil
-
 }
 
+// Stop stops the Entrypoint and all subsystems.
 func (srv *Entrypoint) Stop() {
 	// Stop enabled subsystems
 	if srv.manager != nil {
@@ -110,6 +112,8 @@ func (srv *Entrypoint) Stop() {
 	}
 }
 
+// Start starts the server used by the Entrypoint, and will block until a
+// termination signal is sent to the process.
 func (srv *Entrypoint) Start() error {
 	return srv.srv.Run()
 }

cmd/agent/service.go

@@ -2,10 +2,14 @@
 
 package main
 
+// IsWindowsService returns whether the current process is running as a Windows
+// Service. On non-Windows platforms, this always returns false.
 func IsWindowsService() bool {
 	return false
 }
 
+// RunService runs the current process as a Windows servce. On non-Windows platforms,
+// this is always a no-op.
 func RunService() error {
 	return nil
 }

cmd/agent/service_windows.go

@@ -17,8 +17,10 @@ import (
 const ServiceName = "Grafana Agent"
 const cmdsAccepted = svc.AcceptStop | svc.AcceptShutdown
 
+// AgentService runs the Grafana Agent as a service.
 type AgentService struct{}
 
+// Execute starts the AgentService.
 func (m *AgentService) Execute(args []string, serviceRequests <-chan svc.ChangeRequest, changes chan<- svc.Status) (ssec bool, errno uint32) {
 	changes <- svc.Status{State: svc.StartPending}
 
@@ -72,6 +74,8 @@ loop:
 	return
 }
 
+// IsWindowsService returns whether the current process is running as a Windows
+// Service. On non-Windows platforms, this always returns false.
 func IsWindowsService() bool {
 	isService, err := svc.IsWindowsService()
 	if err != nil {
@@ -80,6 +84,8 @@ func IsWindowsService() bool {
 	return isService
 }
 
+// RunService runs the current process as a Windows servce. On non-Windows platforms,
+// this is always a no-op.
 func RunService() error {
 	return svc.Run(ServiceName, &AgentService{})
 }

pkg/agentctl/samples.go

@@ -11,6 +11,10 @@ import (
 	"github.com/prometheus/prometheus/tsdb/wal"
 )
 
+// SampleStats are statistics for samples for a series within the WAL. Each
+// instance represents a unique series based on its labels, and holds the range
+// of timestamps found for all samples including the total number of samples
+// for that series.
 type SampleStats struct {
 	Labels  labels.Labels
 	From    time.Time

pkg/agentctl/walstats.go

@@ -46,7 +46,7 @@ type WALStats struct {
 	Targets []WALTargetStats
 }
 
-// Samples returns the number of Series across all targets.
+// Series returns the number of series across all targets.
 func (s WALStats) Series() int {
 	var series int
 	for _, t := range s.Targets {

pkg/integrations/agent/agent.go

@@ -18,14 +18,17 @@ type Config struct {
 	Common config.Common `yaml:",inline"`
 }
 
+// Name returns the name of the integration that this config represents.
 func (c *Config) Name() string {
 	return "agent"
 }
 
+// CommonConfig returns the common settings shared across all integrations.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts this config into an instance of an integration.
 func (c *Config) NewIntegration(_ log.Logger) (integrations.Integration, error) {
 	return New(c), nil
 }
@@ -40,6 +43,7 @@ type Integration struct {
 	c *Config
 }
 
+// New creates a new Agent integration.
 func New(c *Config) *Integration {
 	return &Integration{c: c}
 }

pkg/integrations/collector_integration.go

@@ -39,7 +39,7 @@ func NewCollectorIntegration(name string, configs ...CollectorIntegrationConfig)
 // CollectorIntegrationConfig defines constructor configuration for NewCollectorIntegration
 type CollectorIntegrationConfig func(integration *CollectorIntegration)
 
-// WithCollector adds more collectors to the CollectorIntegration being created.
+// WithCollectors adds more collectors to the CollectorIntegration being created.
 func WithCollectors(cs ...prometheus.Collector) CollectorIntegrationConfig {
 	return func(i *CollectorIntegration) {
 		i.cs = append(i.cs, cs...)

pkg/integrations/consul_exporter/consul_exporter.go

@@ -11,6 +11,7 @@ import (
 	"github.com/prometheus/consul_exporter/pkg/exporter"
 )
 
+// DefaultConfig holds the default settings for the consul_exporter integration.
 var DefaultConfig = Config{
 	Server:        "http://localhost:8500",
 	Timeout:       500 * time.Millisecond,
@@ -47,14 +48,17 @@ func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error {
 	return unmarshal((*plain)(c))
 }
 
+// Name returns the name of the integration.
 func (c *Config) Name() string {
 	return "consul_exporter"
 }
 
+// CommonConfig returns the common set of settings for this integration.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts the config into an instance of an integration.
 func (c *Config) NewIntegration(l log.Logger) (integrations.Integration, error) {
 	return New(l, c)
 }

pkg/integrations/dnsmasq_exporter/dnsmasq_exporter.go

@@ -26,14 +26,17 @@ type Config struct {
 	LeasesPath string `yaml:"leases_path"`
 }
 
+// Name returns the name of the integration that this config is for.
 func (c *Config) Name() string {
 	return "dnsmasq_exporter"
 }
 
+// CommonConfig returns the set of common settings shared across all integrations.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts this config into an instance of an integration.
 func (c *Config) NewIntegration(l log.Logger) (integrations.Integration, error) {
 	return New(l, c)
 }

pkg/integrations/elasticsearch_exporter/elasticsearch_exporter.go

@@ -19,6 +19,8 @@ import (
 	"github.com/justwatchcom/elasticsearch_exporter/pkg/clusterinfo"
 )
 
+// DefaultConfig holds the default settings for the elasticsearch_exporter
+// integration.
 var DefaultConfig = Config{
 	Address:                   "http://localhost:9200",
 	Timeout:                   5 * time.Second,
@@ -70,10 +72,13 @@ func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error {
 	return unmarshal((*plain)(c))
 }
 
+// Name returns the name of the integration that this config represents.
 func (c *Config) Name() string {
 	return "elasticsearch_exporter"
 }
 
+// CommonConfig returns the common settings shared across all configs for
+// integrations.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }

pkg/integrations/manager.go

@@ -29,14 +29,13 @@ var (
 	}, []string{"integration_name"})
 )
 
-var (
-	DefaultManagerConfig = ManagerConfig{
-		ScrapeIntegrations:        true,
-		IntegrationRestartBackoff: 5 * time.Second,
-		UseHostnameLabel:          true,
-		ReplaceInstanceLabel:      true,
-	}
-)
+// DefaultManagerConfig holds the default settings for integrations.
+var DefaultManagerConfig = ManagerConfig{
+	ScrapeIntegrations:        true,
+	IntegrationRestartBackoff: 5 * time.Second,
+	UseHostnameLabel:          true,
+	ReplaceInstanceLabel:      true,
+}
 
 // ManagerConfig holds the configuration for all integrations.
 type ManagerConfig struct {
@@ -308,6 +307,7 @@ func (m *Manager) scrapeServiceDiscovery() discovery.Configs {
 	}
 }
 
+// WireAPI routes integrations to the given router.
 func (m *Manager) WireAPI(r *mux.Router) error {
 	for c, i := range m.integrations {
 		integrationsRoot := fmt.Sprintf("/integrations/%s", c.Name())

pkg/integrations/memcached_exporter/memcached_exporter.go

@@ -35,14 +35,17 @@ func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error {
 	return unmarshal((*plain)(c))
 }
 
+// Name returns the name of the integration that this config represents.
 func (c *Config) Name() string {
 	return "memcached_exporter"
 }
 
+// CommonConfig returns the common settings shared across all integratons.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts this config into an instance of an integration.
 func (c *Config) NewIntegration(l log.Logger) (integrations.Integration, error) {
 	return New(l, c)
 }

pkg/integrations/mysqld_exporter/mysqld-exporter.go

@@ -13,6 +13,7 @@ import (
 	"github.com/prometheus/mysqld_exporter/collector"
 )
 
+// DefaultConfig holds the default settings for the mysqld_exporter integration.
 var DefaultConfig = Config{
 	LockWaitTimeout: 2,
 
@@ -73,14 +74,17 @@ func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error {
 	return unmarshal((*plain)(c))
 }
 
+// Name returns the name of the integration that this config represents.
 func (c *Config) Name() string {
 	return "mysqld_exporter"
 }
 
+// CommonConfig returns the common settings shared across all integrations.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts this config into an instance of an integration.
 func (c *Config) NewIntegration(l log.Logger) (integrations.Integration, error) {
 	return New(l, c)
 }

pkg/integrations/node_exporter/config.go

@@ -118,14 +118,17 @@ func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error {
 	return unmarshal((*plain)(c))
 }
 
+// Name returns the name of the integration that this config represents.
 func (c *Config) Name() string {
 	return "node_exporter"
 }
 
+// CommonConfig returns the common configs that are shared across all integrations.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts this config into an instance of an integration.
 func (c *Config) NewIntegration(l log.Logger) (integrations.Integration, error) {
 	return New(l, c)
 }

pkg/integrations/postgres_exporter/postgres_exporter.go

@@ -12,8 +12,6 @@ import (
 	"github.com/wrouesnel/postgres_exporter/exporter"
 )
 
-var DefaultConfig = Config{}
-
 // Config controls the postgres_exporter integration.
 type Config struct {
 	Common config.Common `yaml:",inline"`
@@ -28,22 +26,18 @@ type Config struct {
 	QueryPath              string   `yaml:"query_path"`
 }
 
-// UnmarshalYAML implements yaml.Unmarshaler for Config.
-func (c *Config) UnmarshalYAML(unmarshal func(interface{}) error) error {
-	*c = DefaultConfig
-
-	type plain Config
-	return unmarshal((*plain)(c))
-}
-
+// Name returns the name of the integration this config is for.
 func (c *Config) Name() string {
 	return "postgres_exporter"
 }
 
+// CommonConfig returns the common set of options shared across all configs for
+// integrations.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts this config into an instance of a configuration.
 func (c *Config) NewIntegration(l log.Logger) (integrations.Integration, error) {
 	return New(l, c)
 }

pkg/integrations/process_exporter/config.go

@@ -9,15 +9,14 @@ import (
 	exporter_config "github.com/ncabatoff/process-exporter/config"
 )
 
-var (
-	DefaultConfig Config = Config{
-		ProcFSPath: "/proc",
-		Children:   true,
-		Threads:    true,
-		SMaps:      true,
-		Recheck:    false,
-	}
-)
+// DefaultConfig holds the default settings for the process_exporter integration.
+var DefaultConfig = Config{
+	ProcFSPath: "/proc",
+	Children:   true,
+	Threads:    true,
+	SMaps:      true,
+	Recheck:    false,
+}
 
 // Config controls the process_exporter integration.
 type Config struct {
@@ -31,21 +30,25 @@ type Config struct {
 	Recheck    bool   `yaml:"recheck_on_scrape"`
 }
 
+// UnmarshalYAML implements yaml.Unmarshaler.
 func (c *Config) UnmarshalYAML(unmarshal func(v interface{}) error) error {
 	*c = DefaultConfig
 
 	type plain Config
 	return unmarshal((*plain)(c))
 }
 
+// Name returns the name of the integration that this config represents.
 func (c *Config) Name() string {
 	return "process_exporter"
 }
 
+// CommonConfig returns the set of common settings shared across all integrations.
 func (c *Config) CommonConfig() config.Common {
 	return c.Common
 }
 
+// NewIntegration converts this config into an instance of an integration.
 func (c *Config) NewIntegration(l log.Logger) (integrations.Integration, error) {
 	return New(l, c)
 }