fix deprecation comment for (FlagSet.)ParseErrorsWhitelist

Commit 7412009 added back these types
and marked them as deprecated, but did not use the correct format as
documented in the [go documentation].

Deprecation comments should be in their own paragraph within the GoDoc,
and start with `Deprecated:`, which is case-sensitive. Currently, the
deprecation comment is not properly detected, and does not show up as
deprecated on [pkg.go.dev].

This patch;

- Fixes the deprecation comments to be in the right format.
- Updates the GoDoc to use a "docs link" to refer to their replacement,
  which creates a link to those types on pkg.go.dev.
- Adds back GoDoc for the deprecated functions to make sure the GoDoc
  is in the correct format and keep linters happy.

[go documentation]: https://go.dev/doc/comment#deprecations
[pkg.go.dev]: https://pkg.go.dev/github.com/spf13/[email protected]#ParseErrorsWhitelist

Signed-off-by: Sebastiaan van Stijn <[email protected]>

Author: thaJeztah

flag.go

@@ -143,8 +143,9 @@ type ParseErrorsAllowlist struct {
 	UnknownFlags bool
 }
 
-// DEPRECATED: please use ParseErrorsAllowlist instead
-// This type will be removed in a future release
+// ParseErrorsWhitelist defines the parsing errors that can be ignored.
+//
+// Deprecated: use [ParseErrorsAllowlist] instead. This type will be removed in a future release.
 type ParseErrorsWhitelist = ParseErrorsAllowlist
 
 // NormalizedName is a flag name that has been normalized according to rules
@@ -165,8 +166,9 @@ type FlagSet struct {
 	// ParseErrorsAllowlist is used to configure an allowlist of errors
 	ParseErrorsAllowlist ParseErrorsAllowlist
 
-	// DEPRECATED: please use ParseErrorsAllowlist instead
-	// This field will be removed in a future release
+	// ParseErrorsAllowlist is used to configure an allowlist of errors.
+	//
+	// Deprecated: use [FlagSet.ParseErrorsAllowlist] instead. This field will be removed in a future release.
 	ParseErrorsWhitelist ParseErrorsAllowlist
 
 	name              string