chore: document printers

pkg/printers/checkstyle.go

@@ -14,25 +14,8 @@ import (
 
 const defaultCheckstyleSeverity = "error"
 
-type checkstyleOutput struct {
-	XMLName xml.Name          `xml:"checkstyle"`
-	Version string            `xml:"version,attr"`
-	Files   []*checkstyleFile `xml:"file"`
-}
-
-type checkstyleFile struct {
-	Name   string             `xml:"name,attr"`
-	Errors []*checkstyleError `xml:"error"`
-}
-
-type checkstyleError struct {
-	Column   int    `xml:"column,attr"`
-	Line     int    `xml:"line,attr"`
-	Message  string `xml:"message,attr"`
-	Severity string `xml:"severity,attr"`
-	Source   string `xml:"source,attr"`
-}
-
+// Checkstyle prints issues in the Checkstyle format.
+// https://checkstyle.org/config.html
 type Checkstyle struct {
 	w io.Writer
 }
@@ -93,3 +76,22 @@ func (p Checkstyle) Print(issues []result.Issue) error {
 
 	return nil
 }
+
+type checkstyleOutput struct {
+	XMLName xml.Name          `xml:"checkstyle"`
+	Version string            `xml:"version,attr"`
+	Files   []*checkstyleFile `xml:"file"`
+}
+
+type checkstyleFile struct {
+	Name   string             `xml:"name,attr"`
+	Errors []*checkstyleError `xml:"error"`
+}
+
+type checkstyleError struct {
+	Column   int    `xml:"column,attr"`
+	Line     int    `xml:"line,attr"`
+	Message  string `xml:"message,attr"`
+	Severity string `xml:"severity,attr"`
+	Source   string `xml:"source,attr"`
+}

pkg/printers/codeclimate.go

@@ -10,23 +10,8 @@ import (
 
 const defaultCodeClimateSeverity = "critical"
 
-// CodeClimateIssue is a subset of the Code Climate spec.
-// https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types
-// It is just enough to support GitLab CI Code Quality.
-// https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format
-type CodeClimateIssue struct {
-	Description string `json:"description"`
-	CheckName   string `json:"check_name"`
-	Severity    string `json:"severity,omitempty"`
-	Fingerprint string `json:"fingerprint"`
-	Location    struct {
-		Path  string `json:"path"`
-		Lines struct {
-			Begin int `json:"begin"`
-		} `json:"lines"`
-	} `json:"location"`
-}
-
+// CodeClimate prints issues in the Code Climate format.
+// https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md
 type CodeClimate struct {
 	w io.Writer
 
@@ -44,7 +29,7 @@ func (p CodeClimate) Print(issues []result.Issue) error {
 	codeClimateIssues := make([]CodeClimateIssue, 0, len(issues))
 
 	for i := range issues {
-		issue := &issues[i]
+		issue := issues[i]
 
 		codeClimateIssue := CodeClimateIssue{}
 		codeClimateIssue.Description = issue.Description()
@@ -63,3 +48,20 @@ func (p CodeClimate) Print(issues []result.Issue) error {
 
 	return json.NewEncoder(p.w).Encode(codeClimateIssues)
 }
+
+// CodeClimateIssue is a subset of the Code Climate spec.
+// https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types
+// It is just enough to support GitLab CI Code Quality.
+// https://docs.gitlab.com/ee/ci/testing/code_quality.html#code-quality-report-format
+type CodeClimateIssue struct {
+	Description string `json:"description"`
+	CheckName   string `json:"check_name"`
+	Severity    string `json:"severity,omitempty"`
+	Fingerprint string `json:"fingerprint"`
+	Location    struct {
+		Path  string `json:"path"`
+		Lines struct {
+			Begin int `json:"begin"`
+		} `json:"lines"`
+	} `json:"location"`
+}

pkg/printers/html.go

@@ -122,6 +122,8 @@ type htmlIssue struct {
 	Code   string
 }
 
+// HTML prints issues in an HTML page.
+// It uses the Cloudflare CDN (cdnjs) and React.
 type HTML struct {
 	w io.Writer
 }

pkg/printers/json.go

@@ -8,8 +8,9 @@ import (
 	"github.com/golangci/golangci-lint/pkg/result"
 )
 
+// JSON prints issues in a JSON representation.
 type JSON struct {
-	rd *report.Data // TODO(ldez) should be drop in v2. Only use by JSON reporter.
+	rd *report.Data
 	w  io.Writer
 }
 

pkg/printers/junitxml.go

@@ -12,34 +12,10 @@ import (
 	"github.com/golangci/golangci-lint/pkg/result"
 )
 
-type testSuitesXML struct {
-	XMLName    xml.Name `xml:"testsuites"`
-	TestSuites []testSuiteXML
-}
-
-type testSuiteXML struct {
-	XMLName   xml.Name      `xml:"testsuite"`
-	Suite     string        `xml:"name,attr"`
-	Tests     int           `xml:"tests,attr"`
-	Errors    int           `xml:"errors,attr"`
-	Failures  int           `xml:"failures,attr"`
-	TestCases []testCaseXML `xml:"testcase"`
-}
-
-type testCaseXML struct {
-	Name      string     `xml:"name,attr"`
-	ClassName string     `xml:"classname,attr"`
-	Failure   failureXML `xml:"failure"`
-	File      string     `xml:"file,attr,omitempty"`
-	Line      int        `xml:"line,attr,omitempty"`
-}
-
-type failureXML struct {
-	Message string `xml:"message,attr"`
-	Type    string `xml:"type,attr"`
-	Content string `xml:",cdata"`
-}
-
+// JunitXML prints issues in the Junit XML format.
+// There is no official specification for the JUnit XML file format,
+// and various tools generate and support different flavors of this format.
+// https://github.com/testmoapp/junitxml
 type JunitXML struct {
 	extended bool
 	w        io.Writer
@@ -97,3 +73,31 @@ func (p JunitXML) Print(issues []result.Issue) error {
 	}
 	return nil
 }
+
+type testSuitesXML struct {
+	XMLName    xml.Name `xml:"testsuites"`
+	TestSuites []testSuiteXML
+}
+
+type testSuiteXML struct {
+	XMLName   xml.Name      `xml:"testsuite"`
+	Suite     string        `xml:"name,attr"`
+	Tests     int           `xml:"tests,attr"`
+	Errors    int           `xml:"errors,attr"`
+	Failures  int           `xml:"failures,attr"`
+	TestCases []testCaseXML `xml:"testcase"`
+}
+
+type testCaseXML struct {
+	Name      string     `xml:"name,attr"`
+	ClassName string     `xml:"classname,attr"`
+	Failure   failureXML `xml:"failure"`
+	File      string     `xml:"file,attr,omitempty"`
+	Line      int        `xml:"line,attr,omitempty"`
+}
+
+type failureXML struct {
+	Message string `xml:"message,attr"`
+	Type    string `xml:"type,attr"`
+	Content string `xml:",cdata"`
+}

pkg/printers/sarif.go

@@ -12,53 +12,9 @@ const (
 	sarifSchemaURI = "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.6.json"
 )
 
-type SarifOutput struct {
-	Version string     `json:"version"`
-	Schema  string     `json:"$schema"`
-	Runs    []sarifRun `json:"runs"`
-}
-
-type sarifRun struct {
-	Tool    sarifTool     `json:"tool"`
-	Results []sarifResult `json:"results"`
-}
-
-type sarifTool struct {
-	Driver struct {
-		Name string `json:"name"`
-	} `json:"driver"`
-}
-
-type sarifResult struct {
-	RuleID    string          `json:"ruleId"`
-	Level     string          `json:"level"`
-	Message   sarifMessage    `json:"message"`
-	Locations []sarifLocation `json:"locations"`
-}
-
-type sarifMessage struct {
-	Text string `json:"text"`
-}
-
-type sarifLocation struct {
-	PhysicalLocation sarifPhysicalLocation `json:"physicalLocation"`
-}
-
-type sarifPhysicalLocation struct {
-	ArtifactLocation sarifArtifactLocation `json:"artifactLocation"`
-	Region           sarifRegion           `json:"region"`
-}
-
-type sarifArtifactLocation struct {
-	URI   string `json:"uri"`
-	Index int    `json:"index"`
-}
-
-type sarifRegion struct {
-	StartLine   int `json:"startLine"`
-	StartColumn int `json:"startColumn"`
-}
-
+// Sarif prints issues in the SARIF format.
+// https://sarifweb.azurewebsites.net/
+// https://docs.oasis-open.org/sarif/sarif/v2.1.0/
 type Sarif struct {
 	w io.Writer
 }
@@ -115,3 +71,50 @@ func (p Sarif) Print(issues []result.Issue) error {
 
 	return json.NewEncoder(p.w).Encode(output)
 }
+
+type SarifOutput struct {
+	Version string     `json:"version"`
+	Schema  string     `json:"$schema"`
+	Runs    []sarifRun `json:"runs"`
+}
+
+type sarifRun struct {
+	Tool    sarifTool     `json:"tool"`
+	Results []sarifResult `json:"results"`
+}
+
+type sarifTool struct {
+	Driver struct {
+		Name string `json:"name"`
+	} `json:"driver"`
+}
+
+type sarifResult struct {
+	RuleID    string          `json:"ruleId"`
+	Level     string          `json:"level"`
+	Message   sarifMessage    `json:"message"`
+	Locations []sarifLocation `json:"locations"`
+}
+
+type sarifMessage struct {
+	Text string `json:"text"`
+}
+
+type sarifLocation struct {
+	PhysicalLocation sarifPhysicalLocation `json:"physicalLocation"`
+}
+
+type sarifPhysicalLocation struct {
+	ArtifactLocation sarifArtifactLocation `json:"artifactLocation"`
+	Region           sarifRegion           `json:"region"`
+}
+
+type sarifArtifactLocation struct {
+	URI   string `json:"uri"`
+	Index int    `json:"index"`
+}
+
+type sarifRegion struct {
+	StartLine   int `json:"startLine"`
+	StartColumn int `json:"startColumn"`
+}

pkg/printers/tab.go

@@ -11,6 +11,7 @@ import (
 	"github.com/golangci/golangci-lint/pkg/result"
 )
 
+// Tab prints issues using tabulation as field separator.
 type Tab struct {
 	printLinterName bool
 	useColors       bool

pkg/printers/teamcity.go

@@ -14,7 +14,8 @@ const (
 	largeLimit = 4000
 )
 
-// TeamCity printer for TeamCity format.
+// TeamCity prints issues in the TeamCity format.
+// https://www.jetbrains.com/help/teamcity/service-messages.html
 type TeamCity struct {
 	w       io.Writer
 	escaper *strings.Replacer

pkg/printers/text.go

@@ -11,6 +11,7 @@ import (
 	"github.com/golangci/golangci-lint/pkg/result"
 )
 
+// Text prints issues with a human friendly representation.
 type Text struct {
 	printIssuedLine bool
 	printLinterName bool