dominikh · catzkorn · Jul 20, 2025 · Jul 20, 2025 · Jul 20, 2025 · Jul 20, 2025
diff --git a/staticcheck/sa1002/sa1002.go b/staticcheck/sa1002/sa1002.go
@@ -20,7 +20,11 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      callcheck.Analyzer(rules),
 	},
 	Doc: &lint.RawDocumentation{
-		Title:    `Invalid format in \'time.Parse\'`,
+		Title: `Invalid format in \'time.Parse\'`,
+		Text: `\'time.Parse\' requires a layout string that uses Go's reference time:
+\"Mon Jan 2 15:04:05 MST 2006\" (Unix date format). The layout must represent
+this date and time exactly. See https://pkg.go.dev/time#pkg-constants for
+layout examples.`,
 		Since:    "2017.1",
 		Severity: lint.SeverityError,
 		MergeIf:  lint.MergeIfAny,

diff --git a/staticcheck/sa1012/sa1012.go b/staticcheck/sa1012/sa1012.go
@@ -21,7 +21,10 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Requires: code.RequiredAnalyzers,
 	},
 	Doc: &lint.RawDocumentation{
-		Title:    `A nil \'context.Context\' is being passed to a function, consider using \'context.TODO\' instead`,
+		Title: `A nil \'context.Context\' is being passed to a function, consider using \'context.TODO\' instead`,
+		Text: `The context package prohibits the use of a \'nil\' context.
+If no parent context is available, a new context should be used,
+e.g. \'context.TODO\' or \'context.Background\'.`,
 		Since:    "2017.1",
 		Severity: lint.SeverityWarning,
 		MergeIf:  lint.MergeIfAny,

diff --git a/staticcheck/sa1014/sa1014.go b/staticcheck/sa1014/sa1014.go
@@ -18,7 +18,11 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      callcheck.Analyzer(checkUnmarshalPointerRules),
 	},
 	Doc: &lint.RawDocumentation{
-		Title:    `Non-pointer value passed to \'Unmarshal\' or \'Decode\'`,
+		Title: `Non-pointer value passed to \'Unmarshal\' or \'Decode\'`,
+		Text: `Functions such as \'encoding/json.Unmarshal\' and
+\'(*encoding/json.Decoder).Decode\' require a pointer to the value that should
+be populated. Passing a non-pointer value results in the function returning an
+error at runtime, as it cannot modify the target value.`,
 		Since:    "2017.1",
 		Severity: lint.SeverityError,
 		MergeIf:  lint.MergeIfAny,

diff --git a/staticcheck/sa1020/sa1020.go b/staticcheck/sa1020/sa1020.go
@@ -20,7 +20,12 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Run:      callcheck.Analyzer(checkListenAddressRules),
 	},
 	Doc: &lint.RawDocumentation{
-		Title:    `Using an invalid host:port pair with a \'net.Listen\'-related function`,
+		Title: `Using an invalid host:port pair with a \'net.Listen\'-related function`,
+		Text: `Functions such as \'net.Listen\', \'net.ListenTCP\', and similar,
+expect a valid network address in the form of host:port. The host, the port,
+or both, can be omitted, e.g. \'localhost:8080\', \':8080\' or \':\' are valid
+host:port pairs.
+See https://pkg.go.dev/net#Listen for the full documentation.`,
 		Since:    "2017.1",
 		Severity: lint.SeverityError,
 		MergeIf:  lint.MergeIfAny,

diff --git a/staticcheck/sa2000/sa2000.go b/staticcheck/sa2000/sa2000.go
@@ -19,7 +19,10 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Requires: code.RequiredAnalyzers,
 	},
 	Doc: &lint.RawDocumentation{
-		Title:    `\'sync.WaitGroup.Add\' called inside the goroutine, leading to a race condition`,
+		Title: `\'(*sync.WaitGroup).Add\' called inside the goroutine, leading to a race condition`,
+		Text: `\'(*sync.WaitGroup).Add\' must be called before starting the goroutine
+it is meant to wait for. Calling \'Add\' inside the goroutine creates a race
+condition between the call to \'Add\' and the call to \'Wait\'.`,
 		Since:    "2017.1",
 		Severity: lint.SeverityWarning,
 		MergeIf:  lint.MergeIfAny,

diff --git a/staticcheck/sa2003/sa2003.go b/staticcheck/sa2003/sa2003.go
@@ -20,7 +20,19 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Requires: []*analysis.Analyzer{buildir.Analyzer},
 	},
 	Doc: &lint.RawDocumentation{
-		Title:    `Deferred \'Lock\' right after locking, likely meant to defer \'Unlock\' instead`,
+		Title: `Deferred \'Lock\' right after locking, likely meant to defer \'Unlock\' instead`,
+		Text: `Deferring a call to \'Lock\' immediately after locking is almost always
+a typo. For example:
+
+    mu.Lock()
+    defer mu.Lock()
+
+While this does not strictly guarantee a deadlock depending on how the
+surrounding code is structured, it is highly likely to be a mistake.
+The intended code was likely this:
+
+    mu.Lock()
+    defer mu.Unlock()`,
 		Since:    "2017.1",
 		Severity: lint.SeverityWarning,
 		MergeIf:  lint.MergeIfAny,

diff --git a/staticcheck/sa4010/sa4010.go b/staticcheck/sa4010/sa4010.go
@@ -16,7 +16,10 @@ var SCAnalyzer = lint.InitializeAnalyzer(&lint.Analyzer{
 		Requires: []*analysis.Analyzer{buildir.Analyzer},
 	},
 	Doc: &lint.RawDocumentation{
-		Title:    `The result of \'append\' will never be observed anywhere`,
+		Title: `The result of \'append\' will never be observed anywhere`,
+		Text: `Calls to \'append\' produce a new slice value. When the result of
+\'append\' is assigned to a variable that is never subsequently read, the
+append operation may have an unintended effect.`,
 		Since:    "2017.1",
 		Severity: lint.SeverityWarning,
 		MergeIf:  lint.MergeIfAll,