From 6e1268702f3a792712c8267b87d9307738b11b41 Mon Sep 17 00:00:00 2001
From: Sebastien Rosset <serosset@cisco.com>
Date: Sun, 24 Oct 2021 15:06:58 -0700
Subject: [PATCH] Add code comments to document source code (#2306)

---
 pkg/commands/config.go         |  2 ++
 pkg/commands/executor.go       |  2 +-
 pkg/config/config.go           |  1 +
 pkg/config/linters_settings.go | 14 +++++++++++++-
 pkg/config/run.go              |  1 +
 pkg/lint/lintersdb/manager.go  |  8 ++++++++
 6 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/pkg/commands/config.go b/pkg/commands/config.go
index 4b63e2e5239f..0f2205970bb6 100644
--- a/pkg/commands/config.go
+++ b/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 == "" {
diff --git a/pkg/commands/executor.go b/pkg/commands/executor.go
index 3edb6e4b0e3b..60c44d82f149 100644
--- a/pkg/commands/executor.go
+++ b/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
diff --git a/pkg/config/config.go b/pkg/config/config.go
index 931ddbbbeed1..06fca64b58b2 100644
--- a/pkg/config/config.go
+++ b/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
 
diff --git a/pkg/config/linters_settings.go b/pkg/config/linters_settings.go
index e9e92e6c5d61..04ddb054521e 100644
--- a/pkg/config/linters_settings.go
+++ b/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"`
 }
diff --git a/pkg/config/run.go b/pkg/config/run.go
index ff6347945e2d..43a5ff2e37e1 100644
--- a/pkg/config/run.go
+++ b/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
diff --git a/pkg/lint/lintersdb/manager.go b/pkg/lint/lintersdb/manager.go
index b086bda65da2..7d26b82475c6 100644
--- a/pkg/lint/lintersdb/manager.go
+++ b/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{})
@@ -597,6 +598,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 {
@@ -619,6 +622,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