Restore conversion of raw documentation to plain text and Markdown

This fixes a regression introduced in 8643e6e. Closes: gh-1544
dominikh · Jun 3, 2024 · ac76929 · ac76929
1 parent cc79ad0
commit ac76929
Show file tree

Hide file tree

Showing 163 changed files with 186 additions and 189 deletions.
diff --git a/add-check.go b/add-check.go
@@ -29,7 +29,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run: run,
 		Requires: []*analysis.Analyzer{},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: "",
 		Text: {{.emptyRaw}},
 		{{- if .quickfix }}

diff --git a/analysis/lint/lint.go b/analysis/lint/lint.go
@@ -17,12 +17,12 @@ type Analyzer struct {
 	// The analyzer's documentation. Unlike go/analysis.Analyzer.Doc,
 	// this field is structured, providing access to severity, options
 	// etc.
-	Doc      *Documentation
+	Doc      *RawDocumentation
 	Analyzer *analysis.Analyzer
 }
 
 func InitializeAnalyzer(a *Analyzer) *Analyzer {
-	a.Analyzer.Doc = a.Doc.String()
+	a.Analyzer.Doc = a.Doc.Compile().String()
 	a.Analyzer.URL = "https://staticcheck.dev/docs/checks/#" + a.Analyzer.Name
 	a.Analyzer.Requires = append(a.Analyzer.Requires, tokenfile.Analyzer)
 	return a
@@ -76,26 +76,22 @@ type Documentation struct {
 	MergeIf    MergeStrategy
 }
 
-func Markdownify(m map[string]*RawDocumentation) map[string]*Documentation {
-	out := make(map[string]*Documentation, len(m))
-	for k, v := range m {
-		out[k] = &Documentation{
-			Title: strings.TrimSpace(stripMarkdown(v.Title)),
-			Text:  strings.TrimSpace(stripMarkdown(v.Text)),
-
-			TitleMarkdown: strings.TrimSpace(toMarkdown(v.Title)),
-			TextMarkdown:  strings.TrimSpace(toMarkdown(v.Text)),
-
-			Before:     strings.TrimSpace(v.Before),
-			After:      strings.TrimSpace(v.After),
-			Since:      v.Since,
-			NonDefault: v.NonDefault,
-			Options:    v.Options,
-			Severity:   v.Severity,
-			MergeIf:    v.MergeIf,
-		}
+func (doc RawDocumentation) Compile() *Documentation {
+	return &Documentation{
+		Title: strings.TrimSpace(stripMarkdown(doc.Title)),
+		Text:  strings.TrimSpace(stripMarkdown(doc.Text)),
+
+		TitleMarkdown: strings.TrimSpace(toMarkdown(doc.Title)),
+		TextMarkdown:  strings.TrimSpace(toMarkdown(doc.Text)),
+
+		Before:     strings.TrimSpace(doc.Before),
+		After:      strings.TrimSpace(doc.After),
+		Since:      doc.Since,
+		NonDefault: doc.NonDefault,
+		Options:    doc.Options,
+		Severity:   doc.Severity,
+		MergeIf:    doc.MergeIf,
 	}
-	return out
 }
 
 func toMarkdown(s string) string {

diff --git a/lintcmd/cmd.go b/lintcmd/cmd.go
@@ -119,7 +119,7 @@ func (cmd *Command) AddBareAnalyzers(as ...*analysis.Analyzer) {
 			text = a.Doc[idx+2:]
 		}
 
-		doc := &lint.Documentation{
+		doc := &lint.RawDocumentation{
 			Title:    title,
 			Text:     text,
 			Severity: lint.SeverityWarning,
@@ -330,7 +330,7 @@ func (cmd *Command) listChecks() int {
 	for _, c := range cs {
 		var title string
 		if c.Doc != nil {
-			title = c.Doc.Title
+			title = c.Doc.Compile().Title
 		}
 		fmt.Printf("%s %s\n", c.Analyzer.Name, title)
 	}
@@ -353,7 +353,7 @@ func (cmd *Command) explain() int {
 		fmt.Fprintln(os.Stderr, explain, "has no documentation")
 		return 1
 	}
-	fmt.Println(check.Doc)
+	fmt.Println(check.Doc.Compile())
 	fmt.Println("Online documentation\n    https://staticcheck.dev/docs/checks#" + check.Analyzer.Name)
 	return 0
 }

diff --git a/lintcmd/sarif.go b/lintcmd/sarif.go
@@ -251,27 +251,28 @@ func (o *sarifFormatter) Format(checks []*lint.Analyzer, diagnostics []diagnosti
 		}},
 	}
 	for _, c := range checks {
+		doc := c.Doc.Compile()
 		run.Tool.Driver.Rules = append(run.Tool.Driver.Rules,
 			sarif.ReportingDescriptor{
 				// We don't set Name, as Name and ID mustn't be identical.
 				ID: c.Analyzer.Name,
 				ShortDescription: sarif.Message{
-					Text:     c.Doc.Title,
-					Markdown: c.Doc.TitleMarkdown,
+					Text:     doc.Title,
+					Markdown: doc.TitleMarkdown,
 				},
 				HelpURI: "https://staticcheck.dev/docs/checks#" + c.Analyzer.Name,
 				// We use our markdown as the plain text version, too. We
 				// use very little markdown, primarily quotations,
 				// indented code blocks and backticks. All of these are
 				// fine as plain text, too.
 				Help: sarif.Message{
-					Text:     sarifFormatText(c.Doc.Format(false)),
-					Markdown: sarifFormatText(c.Doc.FormatMarkdown(false)),
+					Text:     sarifFormatText(doc.Format(false)),
+					Markdown: sarifFormatText(doc.FormatMarkdown(false)),
 				},
 				DefaultConfiguration: sarif.ReportingConfiguration{
 					// TODO(dh): we could figure out which checks were disabled globally
 					Enabled: true,
-					Level:   sarifLevel(c.Doc.Severity),
+					Level:   sarifLevel(doc.Severity),
 				},
 			})
 	}

diff --git a/quickfix/qf1001/qf1001.go b/quickfix/qf1001/qf1001.go
@@ -21,7 +21,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      CheckDeMorgan,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    "Apply De Morgan's law",
 		Since:    "2021.1",
 		Severity: lint.SeverityHint,

diff --git a/quickfix/qf1002/qf1002.go b/quickfix/qf1002/qf1002.go
@@ -22,7 +22,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: "Convert untagged switch to tagged switch",
 		Text: `
 An untagged switch that compares a single variable against a series of

diff --git a/quickfix/qf1003/qf1003.go b/quickfix/qf1003/qf1003.go
@@ -22,7 +22,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: "Convert if/else-if chain to tagged switch",
 		Text: `
 A series of if/else-if checks comparing the same variable against

diff --git a/quickfix/qf1004/qf1004.go b/quickfix/qf1004/qf1004.go
@@ -22,7 +22,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    `Use \'strings.ReplaceAll\' instead of \'strings.Replace\' with \'n == -1\'`,
 		Since:    "2021.1",
 		Severity: lint.SeverityHint,

diff --git a/quickfix/qf1005/qf1005.go b/quickfix/qf1005/qf1005.go
@@ -23,7 +23,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    `Expand call to \'math.Pow\'`,
 		Text:     `Some uses of \'math.Pow\' can be simplified to basic multiplication.`,
 		Before:   `math.Pow(x, 2)`,

diff --git a/quickfix/qf1006/qf1006.go b/quickfix/qf1006/qf1006.go
@@ -21,7 +21,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Lift \'if\'+\'break\' into loop condition`,
 		Before: `
 for {

diff --git a/quickfix/qf1007/qf1007.go b/quickfix/qf1007/qf1007.go
@@ -20,7 +20,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: "Merge conditional assignment into variable declaration",
 		Before: `
 x := false

diff --git a/quickfix/qf1008/qf1008.go b/quickfix/qf1008/qf1008.go
@@ -21,7 +21,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    "Omit embedded fields from selector expression",
 		Since:    "2021.1",
 		Severity: lint.SeverityHint,

diff --git a/quickfix/qf1009/qf1009.go b/quickfix/qf1009/qf1009.go
@@ -20,7 +20,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    `Use \'time.Time.Equal\' instead of \'==\' operator`,
 		Since:    "2021.1",
 		Severity: lint.SeverityInfo,

diff --git a/quickfix/qf1010/qf1010.go b/quickfix/qf1010/qf1010.go
@@ -21,7 +21,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    "Convert slice of bytes to string when printing it",
 		Since:    "2021.1",
 		Severity: lint.SeverityHint,

diff --git a/quickfix/qf1011/qf1011.go b/quickfix/qf1011/qf1011.go
@@ -11,7 +11,7 @@ func init() {
 
 var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 	Analyzer: sharedcheck.RedundantTypeInDeclarationChecker("could", true),
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    "Omit redundant type from variable declaration",
 		Since:    "2021.1",
 		Severity: lint.SeverityHint,

diff --git a/quickfix/qf1012/qf1012.go b/quickfix/qf1012/qf1012.go
@@ -23,7 +23,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:    `Use \'fmt.Fprintf(x, ...)\' instead of \'x.Write(fmt.Sprintf(...))\'`,
 		Since:    "2022.1",
 		Severity: lint.SeverityHint,

diff --git a/simple/s1000/s1000.go b/simple/s1000/s1000.go
@@ -19,7 +19,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Use plain channel send or receive instead of single-case select`,
 		Text: `Select statements with a single case can be replaced with a simple
 send or receive.`,

diff --git a/simple/s1001/s1001.go b/simple/s1001/s1001.go
@@ -23,7 +23,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Replace for loop with call to copy`,
 		Text: `
 Use \'copy()\' for copying elements from one slice to another. For

diff --git a/simple/s1002/s1002.go b/simple/s1002/s1002.go
@@ -24,7 +24,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:  `Omit comparison with boolean constant`,
 		Before: `if x == true {}`,
 		After:  `if x {}`,

diff --git a/simple/s1003/s1003.go b/simple/s1003/s1003.go
@@ -21,7 +21,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:   `Replace call to \'strings.Index\' with \'strings.Contains\'`,
 		Before:  `if strings.Index(x, y) != -1 {}`,
 		After:   `if strings.Contains(x, y) {}`,

diff --git a/simple/s1004/s1004.go b/simple/s1004/s1004.go
@@ -22,7 +22,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      CheckBytesCompare,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:   `Replace call to \'bytes.Compare\' with \'bytes.Equal\'`,
 		Before:  `if bytes.Compare(x, y) == 0 {}`,
 		After:   `if bytes.Equal(x, y) {}`,

diff --git a/simple/s1005/s1005.go b/simple/s1005/s1005.go
@@ -22,7 +22,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Drop unnecessary use of the blank identifier`,
 		Text:  `In many cases, assigning to the blank identifier is unnecessary.`,
 		Before: `

diff --git a/simple/s1006/s1006.go b/simple/s1006/s1006.go
@@ -18,7 +18,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:   `Use \"for { ... }\" for infinite loops`,
 		Text:    `For infinite loops, using \'for { ... }\' is the most idiomatic choice.`,
 		Since:   "2017.1",

diff --git a/simple/s1007/s1007.go b/simple/s1007/s1007.go
@@ -22,7 +22,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Simplify regular expression by using raw string literal`,
 		Text: `Raw string literals use backticks instead of quotation marks and do not support
 any escape sequences. This means that the backslash can be used

diff --git a/simple/s1008/s1008.go b/simple/s1008/s1008.go
@@ -22,7 +22,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Simplify returning boolean expression`,
 		Before: `
 if <expr> {

diff --git a/simple/s1009/s1009.go b/simple/s1009/s1009.go
@@ -24,7 +24,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Omit redundant nil check on slices`,
 		Text: `The \'len\' function is defined for all slices, even nil ones, which have
 a length of zero. It is not necessary to check if a slice is not nil

diff --git a/simple/s1010/s1010.go b/simple/s1010/s1010.go
@@ -20,7 +20,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Omit default slice index`,
 		Text: `When slicing, the second index defaults to the length of the value,
 making \'s[n:len(s)]\' and \'s[n:]\' equivalent.`,

diff --git a/simple/s1011/s1011.go b/simple/s1011/s1011.go
@@ -24,7 +24,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer, purity.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Use a single \'append\' to concatenate two slices`,
 		Before: `
 for _, e := range y {

diff --git a/simple/s1012/s1012.go b/simple/s1012/s1012.go
@@ -20,7 +20,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Replace \'time.Now().Sub(x)\' with \'time.Since(x)\'`,
 		Text: `The \'time.Since\' helper has the same effect as using \'time.Now().Sub(x)\'
 but is easier to read.`,

diff --git a/simple/s1016/s1016.go b/simple/s1016/s1016.go
@@ -23,7 +23,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Use a type conversion instead of manually copying struct fields`,
 		Text: `Two struct types with identical fields can be converted between each
 other. In older versions of Go, the fields had to have identical

diff --git a/simple/s1017/s1017.go b/simple/s1017/s1017.go
@@ -23,7 +23,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Replace manual trimming with \'strings.TrimPrefix\'`,
 		Text: `Instead of using \'strings.HasPrefix\' and manual slicing, use the
 \'strings.TrimPrefix\' function. If the string doesn't start with the

diff --git a/simple/s1018/s1018.go b/simple/s1018/s1018.go
@@ -21,7 +21,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Use \"copy\" for sliding elements`,
 		Text: `\'copy()\' permits using the same source and destination slice, even with
 overlapping ranges. This makes it ideal for sliding elements in a

diff --git a/simple/s1019/s1019.go b/simple/s1019/s1019.go
@@ -23,7 +23,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title: `Simplify \"make\" call by omitting redundant arguments`,
 		Text: `The \"make\" function has default values for the length and capacity
 arguments. For channels, the length defaults to zero, and for slices,

diff --git a/simple/s1020/s1020.go b/simple/s1020/s1020.go
@@ -21,7 +21,7 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      run,
 		Requires: []*analysis.Analyzer{inspect.Analyzer, generated.Analyzer},
 	},
-	Doc: &lint.Documentation{
+	Doc: &lint.RawDocumentation{
 		Title:   `Omit redundant nil check in type assertion`,
 		Before:  `if _, ok := i.(T); ok && i != nil {}`,
 		After:   `if _, ok := i.(T); ok {}`,