Add code comments to document source code (#2306)

Author: sebastien-rosset

pkg/commands/config.go

@@ -35,6 +35,8 @@ func (e *Executor) initConfig() {
 	cmd.AddCommand(pathCmd)
 }
 
+// getUsedConfig returns the resolved path to the golangci config file, or the empty string
+// if no configuration could be found.
 func (e *Executor) getUsedConfig() string {
 	usedConfigFile := viper.ConfigFileUsed()
 	if usedConfigFile == "" {

pkg/commands/executor.go

@@ -38,7 +38,7 @@ type Executor struct {
 	exitCode              int
 	version, commit, date string
 
-	cfg               *config.Config
+	cfg               *config.Config // cfg is the unmarshaled data from the golangci config file.
 	log               logutils.Log
 	reportData        report.Data
 	DBManager         *lintersdb.Manager

pkg/config/config.go

@@ -1,5 +1,6 @@
 package config
 
+// Config encapsulates the config data specified in the golangci yaml config file.
 type Config struct {
 	Run Run
 

pkg/config/linters_settings.go

@@ -501,8 +501,20 @@ type WSLSettings struct {
 	ForceCaseTrailingWhitespaceLimit int  `mapstructure:"force-case-trailing-whitespace"`
 }
 
+// CustomLinterSettings encapsulates the meta-data of a private linter.
+// For example, a private linter may be added to the golangci config file as shown below.
+//
+// linters-settings:
+//  custom:
+//    example:
+//      path: /example.so
+//      description: The description of the linter
+//      original-url: github.com/golangci/example-linter
 type CustomLinterSettings struct {
-	Path        string
+	// Path to a plugin *.so file that implements the private linter.
+	Path string
+	// Description describes the purpose of the private linter.
 	Description string
+	// The URL containing the source code for the private linter.
 	OriginalURL string `mapstructure:"original-url"`
 }

pkg/config/run.go

@@ -2,6 +2,7 @@ package config
 
 import "time"
 
+// Run encapsulates the config options for running the linter analysis.
 type Run struct {
 	IsVerbose           bool `mapstructure:"verbose"`
 	Silent              bool

pkg/lint/lintersdb/manager.go

@@ -35,6 +35,7 @@ func NewManager(cfg *config.Config, log logutils.Log) *Manager {
 	return m
 }
 
+// WithCustomLinters loads private linters that are specified in the golangci config file.
 func (m *Manager) WithCustomLinters() *Manager {
 	if m.log == nil {
 		m.log = report.NewLogWrapper(logutils.NewStderrLog(""), &report.Data{})
@@ -594,6 +595,8 @@ func (m Manager) GetAllLinterConfigsForPreset(p string) []*linter.Config {
 	return ret
 }
 
+// loadCustomLinterConfig loads the configuration of private linters.
+// Private linters are dynamically loaded from .so plugin files.
 func (m Manager) loadCustomLinterConfig(name string, settings config.CustomLinterSettings) (*linter.Config, error) {
 	analyzer, err := m.getAnalyzerPlugin(settings.Path)
 	if err != nil {
@@ -616,6 +619,11 @@ type AnalyzerPlugin interface {
 	GetAnalyzers() []*analysis.Analyzer
 }
 
+// getAnalyzerPlugin loads a private linter as specified in the config file,
+// loads the plugin from a .so file, and returns the 'AnalyzerPlugin' interface
+// implemented by the private plugin.
+// An error is returned if the private linter cannot be loaded or the linter
+// does not implement the AnalyzerPlugin interface.
 func (m Manager) getAnalyzerPlugin(path string) (AnalyzerPlugin, error) {
 	if !filepath.IsAbs(path) {
 		// resolve non-absolute paths relative to config file's directory