docs: add godoc for all processors

Author: ldez

pkg/result/processors/autogenerated_exclude.go

@@ -39,6 +39,10 @@ type fileSummary struct {
 	generated bool
 }
 
+// AutogeneratedExclude filters generated files.
+// - mode "lax": see [isGeneratedFileLax] documentation.
+// - mode "strict": see [isGeneratedFileStrict] documentation.
+// - mode "disable": skips this processor.
 type AutogeneratedExclude struct {
 	debugf logutils.DebugFunc
 

pkg/result/processors/cgo.go

@@ -10,10 +10,11 @@ import (
 
 var _ Processor = (*Cgo)(nil)
 
-// Cgo some linters (e.g. gosec, deadcode) return incorrect filepaths for cgo issues,
-// also cgo files have strange issues looking like false positives.
+// Cgo filters cgo artifacts.
 //
-// Require absolute filepath.
+// Some linters (e.g. gosec, etc.) return incorrect file paths for cgo files.
+//
+// Require absolute file path.
 type Cgo struct {
 	goCacheDir string
 }

pkg/result/processors/diff.go

@@ -18,6 +18,12 @@ const envGolangciDiffProcessorPatch = "GOLANGCI_DIFF_PROCESSOR_PATCH"
 
 var _ Processor = (*Diff)(nil)
 
+// Diff filters issues based on options `new`, `new-from-rev`, etc.
+//
+// Uses `git`.
+// The paths inside the patch are relative to the path where git/golangci-lint is run.
+//
+// Warning: it doesn't use `path-prefix` option.
 type Diff struct {
 	onlyNew       bool
 	fromRev       string

pkg/result/processors/exclude.go

@@ -11,6 +11,7 @@ import (
 
 var _ Processor = (*Exclude)(nil)
 
+// Exclude filters reports only based on regular expressions applied to the report text.
 type Exclude struct {
 	name string
 

pkg/result/processors/exclude_rules.go

@@ -15,6 +15,13 @@ type excludeRule struct {
 	baseRule
 }
 
+// ExcludeRules filters reports based on multiple criteria:
+// 	- linter names (string)
+//	- file path (regular expressions)
+//	- text (regular expressions)
+//	- code source (regular expressions)
+//
+// It uses the shortest relative paths and `path-prefix` option.
 type ExcludeRules struct {
 	name string
 

pkg/result/processors/filename_unadjuster.go

@@ -22,11 +22,13 @@ type adjustMap struct {
 	m map[string]posMapper
 }
 
-// FilenameUnadjuster is needed because a lot of linters use `fset.Position(f.Pos())` to get filename.
-// And they return adjusted filename (e.g.` *.qtpl`) for an issue.
+// FilenameUnadjuster fixes filename based on adjusted and unadjusted position (related to line directives and cgo).
+//
+// A lot of linters use `fset.Position(f.Pos())` to get filename,
+// and they return adjusted filename (e.g.` *.qtpl`) for an issue.
 // We need restore real `.go` filename to properly output it, parse it, etc.
 //
-// Require absolute filepath.
+// Require absolute file path.
 type FilenameUnadjuster struct {
 	m                   map[string]posMapper // map from adjusted filename to position mapper: adjusted -> unadjusted position
 	log                 logutils.Log

pkg/result/processors/fixer.go

@@ -31,6 +31,8 @@ var _ Processor = (*Fixer)(nil)
 
 const filePerm = 0644
 
+// Fixer fixes reports if possible.
+// The reports that are not fixed are passed to the next processor.
 type Fixer struct {
 	cfg       *config.Config
 	log       logutils.Log

pkg/result/processors/identifier_marker.go

@@ -13,6 +13,9 @@ type replacePattern struct {
 	repl string
 }
 
+// IdentifierMarker modifies report text.
+// It must be before [Exclude] and [ExcludeRules]:
+// users configure exclusions based on the modified text.
 type IdentifierMarker struct {
 	patterns map[string][]replacePattern
 }

pkg/result/processors/invalid_issue.go

@@ -9,6 +9,9 @@ import (
 
 var _ Processor = (*InvalidIssue)(nil)
 
+// InvalidIssue filters invalid reports.
+// - non-go files (except `go.mod`)
+// - reports without file path
 type InvalidIssue struct {
 	log logutils.Log
 }

pkg/result/processors/max_from_linter.go

@@ -8,6 +8,7 @@ import (
 
 var _ Processor = (*MaxFromLinter)(nil)
 
+// MaxFromLinter limits the number of reports from the same linter.
 type MaxFromLinter struct {
 	linterCounter map[string]int
 	limit         int

pkg/result/processors/max_per_file_from_linter.go

@@ -7,6 +7,7 @@ import (
 
 var _ Processor = (*MaxPerFileFromLinter)(nil)
 
+// MaxPerFileFromLinter limits the number of reports by file and by linter.
 type MaxPerFileFromLinter struct {
 	fileLinterCounter          fileLinterCounter
 	maxPerFileFromLinterConfig map[string]int

pkg/result/processors/max_same_issues.go

@@ -10,6 +10,7 @@ import (
 
 var _ Processor = (*MaxSameIssues)(nil)
 
+// MaxSameIssues limits the number of reports with the same text.
 type MaxSameIssues struct {
 	textCounter map[string]int
 	limit       int

pkg/result/processors/nolint.go

@@ -64,6 +64,7 @@ type fileData struct {
 	ignoredRanges []ignoredRange
 }
 
+// Nolint filters and sorts reports related to `nolint` directives.
 type Nolint struct {
 	fileCache      map[string]*fileData
 	dbManager      *lintersdb.Manager

pkg/result/processors/path_prefixer.go

@@ -7,7 +7,8 @@ import (
 
 var _ Processor = (*PathPrefixer)(nil)
 
-// PathPrefixer adds a customizable prefix to every output path
+// PathPrefixer adds a customizable path prefix to report file paths for user facing.
+// It uses the shortest relative paths and `path-prefix` option.
 type PathPrefixer struct {
 	prefix string
 }
@@ -24,11 +25,14 @@ func (*PathPrefixer) Name() string {
 
 // Process adds the prefix to each path
 func (p *PathPrefixer) Process(issues []result.Issue) ([]result.Issue, error) {
-	if p.prefix != "" {
-		for i := range issues {
-			issues[i].Pos.Filename = fsutils.WithPathPrefix(p.prefix, issues[i].Pos.Filename)
-		}
+	if p.prefix == "" {
+		return issues, nil
 	}
+
+	for i := range issues {
+		issues[i].Pos.Filename = fsutils.WithPathPrefix(p.prefix, issues[i].Pos.Filename)
+	}
+
 	return issues, nil
 }
 

pkg/result/processors/path_prettifier.go

@@ -10,6 +10,7 @@ import (
 
 var _ Processor = (*PathPrettifier)(nil)
 
+// PathPrettifier modifies report file path with the shortest relative path.
 type PathPrettifier struct {
 	log logutils.Log
 }

pkg/result/processors/path_shortener.go

@@ -10,6 +10,8 @@ import (
 
 var _ Processor = (*PathShortener)(nil)
 
+// PathShortener modifies text of the reports to reduce file path inside the text.
+// It uses the rooted path name corresponding to the current directory (`wd`).
 type PathShortener struct {
 	wd string
 }

pkg/result/processors/severity.go

@@ -19,6 +19,10 @@ type severityRule struct {
 	severity string
 }
 
+// Severity modifies report severity.
+// It uses the same [baseRule] structure as [ExcludeRules] processor.
+//
+// Warning: it doesn't use `path-prefix` option.
 type Severity struct {
 	name string
 

pkg/result/processors/skip_dirs.go

@@ -21,6 +21,8 @@ var StdExcludeDirRegexps = []string{
 	normalizePathRegex("builtin"),
 }
 
+// SkipDirs filters reports based on directory names.
+// It uses the shortest relative paths and `path-prefix` option.
 type skipStat struct {
 	pattern string
 	count   int

pkg/result/processors/skip_files.go

@@ -10,6 +10,9 @@ import (
 
 var _ Processor = (*SkipFiles)(nil)
 
+// SkipFiles filters reports based on filename.
+//
+// It uses the shortest relative paths and `path-prefix` option.
 type SkipFiles struct {
 	patterns   []*regexp.Regexp
 	pathPrefix string

pkg/result/processors/sort_results.go

@@ -31,6 +31,10 @@ var _ Processor = (*SortResults)(nil)
 
 type issueComparator func(a, b *result.Issue) int
 
+// SortResults sorts reports based on criteria:
+// - file names, line numbers, positions
+// - linter names
+// - severity names
 type SortResults struct {
 	cmps map[string][]issueComparator
 

pkg/result/processors/source_code.go

@@ -8,6 +8,13 @@ import (
 
 var _ Processor = (*SourceCode)(nil)
 
+// SourceCode modifies displayed information based on [result.Issue.GetLineRange()].
+//
+// This is used:
+// - to display the "UnderLinePointer".
+// - in some rare cases to display multiple lines instead of one (ex: `dupl`)
+//
+// It requires to use [fsutils.LineCache] ([fsutils.FileCache]) to get the file information before the fixes.
 type SourceCode struct {
 	lineCache *fsutils.LineCache
 	log       logutils.Log

pkg/result/processors/uniq_by_line.go

@@ -9,6 +9,7 @@ const uniqByLineLimit = 1
 
 var _ Processor = (*UniqByLine)(nil)
 
+// UniqByLine filters reports to keep only one report by line of code.
 type UniqByLine struct {
 	fileLineCounter fileLineCounter
 	cfg             *config.Config